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) -- The event category

• event_type (str) --

  The event category. Must be one of:

  • Success

  • Error

  • Warning

  • Information

  • AuditSuccess

  • AuditFailure

• event_strings (list) -- A list of strings

• event_data (bytes) -- Event data. Strings will be converted to bytes

• event_sid (sid) -- The SID for the event

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) -- Path to backup file

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) -- 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) -- The filter to apply to the log

• records (int) -- The number of records to return

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

• raw (bool) -- 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]]]"