# 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, `&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`, 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]]]'