Windows.EventLogs.Evtx

Parses and returns events from Windows evtx logs.

Each event is returned in full, but results can be narrowed using a glob pattern for evtx files, a timespan, and regexes to match the evtx path, event channel, and/or event ID:

  • EvtxGlob: glob of event log files (evtx) to target
  • StartDate: earliest event created timestamp to target
  • EndDate: latest event created timestamp to target
  • PathRegex: a regex to match against paths returned from EvtxGlob
  • ChannelRegex: a regex to match against the event channel
  • IDRegex: a regex to match against the event ID

Gathering these logs enables VQL analysis (e.g., via notebooks) and bulk export (e.g., to elasticsearch) for additional processing. It can also be used as the basis for custom artifacts with more in-depth filtering.

Note: This artifact can be resource intensive.

  • Parsing and aggregating may use high amounts of CPU on the client. Consider reducing the ops/second or narrowing the glob/path regex if necessary.
  • Parsing may use significant memory and time when searching VSS volumes and deduplicating events. This is proportional to the evtx file size and number of VSS copies. Consider whether the extra events are worth the resources.
  • Parsing many event logs may take longer than the default timeout. When parsing all log files and searching VSS, consider doubling the default or more (especially with reduced ops/second, or if targets have high-volume 3rd-party log sources such as Sysmon).
  • The artifact routinely produces hundreds of thousands of rows per host. Consider filtering results using path, channel, and ID regexes if necessary.

Inspired by others in Windows.EventLogs.*, many by Matt Green (@mgreen27).


name: Windows.EventLogs.Evtx

description: |
  Parses and returns events from Windows evtx logs.

  Each event is returned in full, but results can be narrowed using a glob
  pattern for evtx files, a timespan, and regexes to match the evtx path, event
  channel, and/or event ID:

  - EvtxGlob: glob of event log files (evtx) to target
  - StartDate: earliest event created timestamp to target
  - EndDate: latest event created timestamp to target
  - PathRegex: a regex to match against paths returned from EvtxGlob
  - ChannelRegex: a regex to match against the event channel
  - IDRegex: a regex to match against the event ID

  Gathering these logs enables VQL analysis (_e.g._, via notebooks) and bulk
  export (_e.g._, to elasticsearch) for additional processing.  It can also be
  used as the basis for custom artifacts with more in-depth filtering.

  **Note: This artifact can be resource intensive.**

  - Parsing and aggregating may use high amounts of CPU on the client. Consider
  reducing the ops/second or narrowing the glob/path regex if necessary.
  - Parsing may use significant memory and time when searching VSS volumes and
  deduplicating events. This is proportional to the evtx file size and number
  of VSS copies. Consider whether the extra events are worth the resources.
  - Parsing many event logs may take longer than the default timeout.  When
  parsing all log files and searching VSS, consider doubling the default or
  more (especially with reduced ops/second, or if targets have high-volume
  3rd-party log sources such as Sysmon).
  - The artifact routinely produces hundreds of thousands of rows per host.
  Consider filtering results using path, channel, and ID regexes if necessary.

  Inspired by others in `Windows.EventLogs.*`, many by Matt Green (@mgreen27).

author: Chris Hendricks (chris@counteractive.net)

precondition: SELECT OS FROM info() WHERE OS = 'windows'

parameters:
  - name: EvtxGlob
    default: '%SystemRoot%\System32\winevt\Logs\*.evtx'
  - name: VSSAnalysisAge
    type: int
    default: 0
    description: |
      If larger than zero we analyze VSS within this many days
      ago. (e.g 7 will analyze all VSS within the last week).  Note
      that when using VSS analysis we have to use the ntfs accessor
      for everything which will be much slower.
  - name: StartDate
    type: timestamp
    description: "Parse events on or after this date (YYYY-MM-DDTmm:hh:ssZ)"
  - name: EndDate
    type: timestamp
    description: "Parse events on or before this date (YYYY-MM-DDTmm:hh:ssZ)"
  - name: PathRegex
    default: "."
    type: regex
  - name: ChannelRegex
    default: "."
    type: regex
  - name: IDRegex
    default: "."
    type: regex

sources:
  - query: |
      LET VSS_MAX_AGE_DAYS <= VSSAnalysisAge
      LET Accessor = if(condition=VSSAnalysisAge > 0, then="ntfs_vss", else="auto")

      // expand provided glob into a list of paths on the file system (fs)
      LET fspaths =
          SELECT OSPath FROM glob(globs=expand(path=EvtxGlob), accessor=Accessor)
          WHERE OSPath =~ PathRegex

      // function returning parsed evtx from list of paths
      LET evtxsearch(pathList) = SELECT * FROM foreach(
            row=pathList,
            query={
              SELECT *,
                timestamp(epoch=int(int=System.TimeCreated.SystemTime)) AS TimeCreated,
                System.Channel as Channel,
                System.EventRecordID as EventRecordID,
                System.EventID.Value as EventID,
                OSPath
              FROM parse_evtx(filename=OSPath, accessor=Accessor)
              WHERE
                if(condition=StartDate,
                   then=TimeCreated >= timestamp(string=StartDate),
                   else=true)
                AND if(condition=EndDate,
                       then=TimeCreated <= timestamp(string=EndDate),
                       else=true)
                AND Channel =~ ChannelRegex
                AND str(str=EventID) =~ IDRegex
            }
          )

      SELECT * FROM evtxsearch(pathList=fspaths)
      GROUP BY EventRecordID, Channel