DOCSEARCHbyAlgolia
Submit Docs

evtx

repository·master·Indexed 21 days ago

https://github.com/omerbenamram/evtx

A high-performance, cross-platform, and 100% safe Rust parser for the Windows XML Event Log (.evtx) format. It provides a library for Rust integration, a CLI utility called evtx_dump for converting logs to XML or JSON, and a WebAssembly-powered browser viewer. Features include multithreading support and offline template rendering via WEVT_TEMPLATE caches.

Tokens
67.1K
Snippets
153
Records
224
Agent score
76%

What's inside evtx

  1. How Parameter Substitution Works in Event Descriptions

    master

    The publisher uses a parameter file to handle dynamic content in event descriptions.

    1. The publisher defines a description string using placeholders like %%2 (e.g., "The system has found %%2").
    2. When the server calls EvtRpcMessageRender, it identifies the %%n pattern.
    3. The server uses the index n to look up the corresponding value in the publisher parameter file.
    4. The value is substituted into the string.

    Note: Unlike description strings, the values in the publisher parameter file cannot be localized; they are used strictly for substitution.

  2. Understand Event Metadata Enumeration (PCONTEXT_HANDLE_EVENT_METADATA_ENUM)

    master

    When a client needs to enumerate event metadata from a publisher, it uses the PCONTEXT_HANDLE_EVENT_METADATA_ENUM context handle. The server manages this by maintaining an event metadata object which contains:

    1. HandleType: An integer identifying the handle type (e.g., if the server uses 5 for PCONTEXT_HANDLE_EVENT_METADATA_ENUM, this field is set to 5).
    2. EventsMetaData: A memory buffer containing the data from the publisher's resource file's events information section.
    3. Enumerator: A numeric integer acting as a cursor to track the current position within the metadata section.

    The server creates this object and casts it to the handle type; when the client returns the handle, the server casts it back to the object to resume enumeration.

  3. Understand Log File Structure and Metadata

    master

    A log is a file system file containing events. Logs can be associated with a specific channel (live event logs) or exist as standalone files (no associated channel).

    Log File Components

    1. File Header: Contains metadata about the event log. Key fields maintained by publishers include:
      • isLogFull: Indicates if the log is full.
      • oldestRecordNumber: The oldest event log record ID.
      • numberOfRecords: Total number of records in the file.
      • curPhysicalRecordNumber: The physical record number of the latest record.
    2. File Body: Consists of all event records formatted in binXML.

    Retrieving Log Info

    Use the EvtGetLogFileInfo method to retrieve properties such as creation time, last access time, last written time, file size, number of events, and the log full flag.

  4. Understand the BinXmlVariant structure

    master

    The BinXmlVariant structure is used for returning information about a channel or backup event log. It is a custom-marshaled structure where integer fields must be in little-endian byte order. The interpretation of the 8-byte union field depends on the type field.

    Structure Layout:

    • union (8 bytes): Data whose interpretation is based on type.
    • count (4 bytes): Not used; must be ignored on receipt.
    • type (4 bytes): Specifies the union type.
    ### BinXmlVariant Types
| Value | Meaning |
| --- | --- |
| BinXmlVarUint32 (0x00000008) | The union field contains an unsigned long int, followed by 4 bytes of arbitrary data that MUST be ignored. |
| BinXmlVarUint64 (0x0000000A) | The union field contains an unsigned __int64. |
| BinXmlVarBool (0x0000000D) | The union field contains an unsigned long int, followed by 4 bytes of arbitrary data that MUST be ignored. |
| BinXmlVarFileTime (0x00000011) | The union field contains a FILETIME (as specified in [MS-DTYP] Appendix A). |

  5. Use XML Bookmarks for Cursor Positioning

    master

    Bookmarks are used to specify a cursor position within an event query or subscription result set. While the server passes binary bookmarks to the client, the client passes bookmarks to the server using an XML representation.

    Bookmark Schema

    Bookmarks are wrapped in a <BookmarkList> element. Each <Bookmark> element defines a position in a specific channel.

    Attributes

    • Channel: The name of the event log channel (e.g., Application). If the channel is part of a container, the container identifier is appended.
    • RecordId: The logical event record number in the specified channel.
    • IsCurrent: A boolean indicating if the event at this cursor position is the most recent one. In a list of multiple bookmarks for different channels, exactly one Bookmark element MUST have IsCurrent="True".
    <!-- Example bookmark for the Application Log -->
<bookmarklist>
  <bookmark channel="Application" RecordId="2004" iscurrent="True" />
</bookmarklist>

  6. Query events using XPath expressions

    master

    Events within log files can be queried using the EventLog Remoting Protocol. Queries are performed using an expression string (typically an XPath query) that selects events based on their XML representation.

    To perform queries, use the following protocol methods:

    • EvtRpcRegisterLogQuery: To register a query job.
    • EvtRpcQueryNext: To retrieve the next events in the query result.
    • EvtRpcQuerySeek: To move the query cursor to a specific position.

  7. How BinXml templates and instances work

    master

    BinXml uses Template Definitions and Template Instances to separate the structure of an event from its data.

    • Template Definition: A BinXml fragment containing substitution tokens (e.g., %1, %2). These tokens map to 0-based substitution identifiers.
    • Template Instance Data: The set of raw values used to replace the tokens.
    • Template Instance: The combination of a Template Definition and its Instance Data.

    Substitution Tokens:

    • 0D: Normal substitution token.
    • 0E: Optional substitution token. If the value identified by this token is NULL in the Template Instance data, the enclosing element or attribute is omitted from the rendered XML.

    Value Spec: Every Template Instance is preceded by a 'Value Spec' which describes the type and length of the values in the instance data. For example, a spec of 04 01 indicates one value of type UINT8 (04) with a length of 1 byte.

    Example of a Template Instance: If a template defines <PropA> %1 </PropA> (binary 01 PropA 02 05 0D 00 04) and the instance data is 0x63, the rendered XML is <PropA> 99 </PropA> (assuming 0x63 is the character 'c' or similar contextually).

  8. Understanding BinXml in MS-EVEN6

    master

    Event information returned by query and subscription methods is encoded in a binary format called BinXml.

    BinXml is a token representation of text XML 1.0. It is designed so that the original XML text can be correctly reproduced from the encoding. While the protocol can be implemented by treating BinXml simply as a method to transmit name-value pairs, many third-party applications convert BinXml to text XML for consumption.

  9. Structure of Publisher Resource Files

    master

    Publisher resource files (typically .dll or .exe files) contain the instrumentation metadata required to describe events. They include:

    • Publisher Information: Identifiers and links.
    • Channel Information: Definitions for event channels.
    • Events Information: Detailed metadata for each event, including:
      • version
      • messageId (used as an index for strings)
      • level (and its description)
      • opcode (and its description)
      • task (and its description)
      • keyword (and its description)
      • template (the event definition)

    Note that the resource file itself does not store the actual description strings; it stores a messageId which acts as an index to look up the real strings in a language-specific resource file.

    [Publisher Information]
<publisher identifier="" ...>

[Channel Information]
<channel identifier="" ...>

[Events information]
<event identifier="">
  <version>
    <messageid for="event" ...>
    <level value="" ...>
      <messageid for="level" ...>
    </level>
    <opcode value="" ...>
      <messageid for="opcode" ...>
    </opcode>
    <task value="" ...>
      <messageid for="task" ...>
    </task>
    <keyword value="" ...>
      <messageid for="keyword" ...>
    </keyword>
  </version>
</event>
</publisher>

  10. Control Server Operations (PCONTEXT_HANDLE_OPERATION_CONTROL)

    master

    To manage long-running server calls, clients can use the PCONTEXT_HANDLE_OPERATION_CONTROL context handle to cancel operations. The server maintains a control object for this handle containing:

    1. HandleType: An integer identifying the handle type (e.g., 6 for PCONTEXT_HANDLE_OPERATION_CONTROL).
    2. OperationPointer: A pointer to the active server operation object (such as a query or subscription object).
    3. Canceled: A Boolean indicating if the client has requested a cancellation.

    This allows the client to signal the server to stop serving a specific call that is taking too long.

  11. Understand the BinXml format in MS-EVEN6

    master

    BinXml is a binary token representation of XML 1.0 used in the EventLog Remoting Protocol. It is designed so that the original XML text can be accurately reproduced from the encoding.

    Key characteristics:

    • Endianness: All numeric values are stored in little-endian format.
    • Alignment: No data alignment is required.
    • Structure: It uses a series of tokens (e.g., OpenStartElementToken, EndElementToken) to define the layout of binary XML large objects (BLOBs).

  12. XPath 1.0 Subset for EventLog Filtering

    master

    The EventLog Remoting Protocol uses a restricted subset of XPath 1.0 to select events. The evaluation is restricted to forward-only, in-order, depth-first traversal of the XML.

    Supported Location Paths:

    • Axis
    • Child
    • Attribute
    • Node tests (including * wildcard)
    • NCName
    • text

    Supported Expressions:

    • Logical: or, and
    • Comparison: =, !=, <=, <, >=, >
    • Literals: ('Expr'), Literal, Number
    • FunctionCall

    Key Restrictions:

    • Absolute location paths are not supported (the root is implied).
    • Generating string values for nodes or expanded names for nodes is not supported.
    • Reverse document order evaluation is not supported.
    • Node sets, namespace scoping, and processing/comment nodes are not supported.