salt.modules.win_event

A module for working with the Windows Event log system. .. versionadded:: 3006.0

salt.modules.win_event.add(log_name, event_id, event_category=0, event_type=None, event_strings=None, event_data=None, event_sid=None)

Adds an event to the application event log.

Parameters:

• log_name (str) -- The name of the application or source

• event_id (int) -- The event ID

• event_category (int, optional) -- The event category. Default is 0

• event_type (str, optional) --

  The event category. Must be one of:

  • Success

  • Error

  • Warning

  • Information

  • AuditSuccess

  • AuditFailure

  Default is None.

• event_strings (list, optional) -- A list of strings. Default is None.

• event_data (bytes, optional) -- Event data. Strings will be converted to bytes. Default is None.

• event_sid (sid, optional) -- The SID for the event. Default is None.

Raises:

• CommandExecutionError -- event_id is not an integer

• CommandExecutionError -- event_category is not an integer

• CommandExecutionError -- event_type is not one of the valid event types

• CommandExecutionError -- event_strings is not a list or string

CLI Example:

# A simple Application event log warning entry
salt '*' win_event.add Application 1234 12 Warning

# A more complex System event log information entry
salt '*' win_event.add System 1234 12 Information '["Event string data 1", "Event string data 2"]' 'Some event data'

# Log to the System Event log with the source "Service Control Manager"
salt '*' win_event.add 'Service Control Manager' 1234 12 Warning '["Event string data 1", "Event string data 2"]' 'Some event data'

# Log to the PowerShell event log with the source "PowerShell (PowerShell)"
salt-call --local win_event.add "PowerShell" 6969 12 Warning

salt.modules.win_event.clear(log_name, backup=None)

Clears the specified event log.

Note

A clear log event will be added to the log after it is cleared.

Parameters:

• log_name (str) -- The name of the log to clear

• backup (str, optional) -- Path to backup file. Default is None.

CLI Example:

salt "*" win_event.clear Application

salt.modules.win_event.count(log_name)

Gets the number of events in the specified.

Parameters:

log_name (str) -- The name of the log

Returns:

The number of events the log contains

Return type:

int

CLI Example:

salt "*" win_event.count Application

salt.modules.win_event.get(log_name)

Get events from the specified log. Get a list of available logs using the win_event.get_log_names function.

Warning

Running this command on a log with thousands of events, such as the Applications log, can take a long time.

Parameters:

log_name (str) -- The name of the log to retrieve.

Returns

tuple: A tuple of events as dictionaries

CLI Example:

salt '*' win_event.get Application

salt.modules.win_event.get_filtered(log_name, all_requirements=True, **kwargs)

Will find events that match the fields and values specified in the kwargs. Kwargs can be any item in the return for the event.

Warning

Running this command on a log with thousands of events, such as the Applications log, can take a long time.

Parameters:

• log_name (str) -- The name of the log to retrieve

• all_requirements (bool, optional) -- True matches all requirements. False matches any requirement. Default is True.

Kwargs:

eventID (int): The event ID number

eventType (int): The event type number. Valid options and their

corresponding meaning are:

• 0 : Success

• 1 : Error

• 2 : Warning

• 4 : Information

• 8 : Audit Success

• 10 : Audit Failure

year (int): The year

month (int): The month

day (int): The day of the month

hour (int): The hour

minute (int): The minute

second (int): The second

eventCategory (int): The event category number

sid (sid): The SID of the user that created the event

sourceName (str): The name of the event source

Returns:

A tuple of dicts of each filtered event

Return type:

tuple

CLI Example:

# Return all events from the Security log with an ID of 1100
salt '*' win_event.get_filtered Security eventID=1100

# Return all events from the System log with an Error (1) event type
salt '*' win_event.get_filtered System eventType=1

# Return all events from System log with an Error (1) type, source is Service Control Manager, and data is netprofm
salt '*' win_event.get_filtered System eventType=1 sourceName='Service Control Manager' data='netprofm'

# Return events from the System log that match any of the kwargs below
salt '*' win_event.get_filtered System eventType=1 sourceName='Service Control Manager' data='netprofm' all_requirements=False

salt.modules.win_event.get_log_names()

Get a list of event logs available on the system

Returns:

A list of event logs available on the system

Return type:

list

CLI Example:

salt '*' win_event.get_log_names

salt.modules.win_event.query(log_name, query_text=None, records=20, latest=True, raw=False)

Query a log for a specific event_id. Return the top number of records specified. Use the win_event.get_log_names to see a list of available logs on the system.

Note

You can use the Windows Event Viewer to create the XPath query for the query_text parameter. Click on Filter Current Log, configure the filter, then click on the XML tab. Copy the text between the two <Select> tags. This will be the contents of the query_text parameter. You will have to convert some codes. For example, > becomes >, < becomes <. Additionally, you'll need to put spaces between comparison operators. For example: this >= that.

Parameters:

• log_name (str) -- The name of the log to query

• query_text (str, optional) -- The filter to apply to the log. Default is None.

• records (int, optional) -- The number of records to return. Default is 20

• latest (bool, optional) -- True will return the newest events. False will return the oldest events. Default is True.

• raw (bool, optional) -- True will return the raw xml results. False will return the xml converted to a dictionary. Default is False.

Returns:

A list of dict objects that contain information about the event

Return type:

list

CLI Example:

# Return the 20 most recent events from the Application log with an event ID of 22
salt '*' win_event.query Application '*[System[(EventID=22)]]'

# Return the 20 most recent events from the Application log with an event ID of 22
# Return raw xml
salt '*' win_event.query Application '*[System[(EventID=22)]]' raw=True

# Return the 20 oldest events from the Application log with an event ID of 22
salt '*' win_event.query Application '*[System[(EventID=22)]]' latest=False

# Return the 20 most recent Critical (1) events from the Application log in the last 12 hours
salt '*' win_event.query Application '*[System[(Level=1) and TimeCreated[timediff(@SystemTime) <= 43200000]]]'

# Return the 5 most recent Error (2) events from the application log
salt '*' win_event.query Application '*[System[(Level=2)]]' records=5

# Return the 20 most recent Warning (3) events from the Windows PowerShell log where the Event Source is PowerShell
salt '*' win_event.query 'Windows PowerShell' '*[System[Provider[@Name="PowerShell"] and (Level=3)]]'

# Return the 20 most recent Information (0 or 4) events from the Microsoft-Windows-PowerShell/Operational on 2022-08-24 with an Event ID of 4103
salt '*' win_event.query 'Microsoft-Windows-PowerShell/Operational' '*[System[(Level=4 or Level=0) and (EventID=4103) and TimeCreated[@SystemTime >= "2022-08-24T06:00:00.000Z"]]]'

# Return the 20 most recent Information (0 or 4) events from the Microsoft-Windows-PowerShell/Operational within the last hour
salt '*' win_event.query 'Microsoft-Windows-PowerShell/Operational' '*[System[(Level=4 or Level=0) and TimeCreated[timediff(@SystemTime) <= 3600000]]]'