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:

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, &gt; becomes >, &lt; 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]]]"