DOCSEARCHbyAlgolia
Submit Docs

pywintrace

repository·master·Indexed 43 days ago

https://github.com/fireeye/pywintrace

A Python wrapper for Windows Event Tracing (ETW) using ctypes. It allows developers to programmatically control ETW sessions as a Controller and Consumer, defining providers and using callbacks to process event data.

Tokens
1.3K
Snippets
3
Records
5
Agent score
5%

What's inside pywintrace

  1. How pywintrace ETW works

    master

    pywintrace is a Python-based ctypes wrapper around Win32 APIs used to control Event Tracing for Windows (ETW) sessions.

    ETW architecture consists of three main components:

    1. Provider: Specified by a GUID, it logs events to buffers.
    2. Controller: Defines and controls the capture session (which providers to include, starting/stopping the session).
    3. Consumer: Receives and processes messages from buffers or files in chronological order.

    This module allows you to act as a Controller and Consumer by defining providers and specifying callbacks to process the resulting event data.

  2. Extend ETW functionality by subclassing etw.ETW

    master

    You can subclass etw.ETW to implement custom pre-capture setup and post-capture teardown logic. By overriding the start() and stop() methods, you can ensure that self.do_capture_setup() and self.do_capture_teardown() are called around the base class operations.

    import time
import etw

class MyETW(etw.ETW):

    def __init__(self, event_callback):
        # define capture provider info
        providers = [etw.ProviderInfo('Some Provider', etw.GUID("{11111111-1111-1111-1111-111111111111}"))]
        super().__init__(providers=providers, event_callback=event_callback)

    def start(self):
        # do pre-capture setup
        self.do_capture_setup()
        super().start()

    def stop(self):
        super().stop()
        # do post-capture teardown
        self.do_capture_teardown()

    def do_capture_setup(self):
        # do whatever setup for capture here
        pass

    def do_capture_teardown(self):
        # do whatever for capture teardown here
        pass


def my_capture():
    # instantiate class
    capture = MyETW(lambda x: print(x))
    # start capture
    capture.start()
    # wait some time to capture data
    time.sleep(5)
    capture.stop()

  3. Capture ETW events using the ETW context manager

    master

    The simplest way to capture events is to use the etw.ETW class as a context manager. You must provide a list of etw.ProviderInfo objects and an event_callback function to handle the incoming data. Inside the context manager, call etw.run('etw') to begin the capture.

    To define a provider, use etw.ProviderInfo(name, guid) where the GUID is wrapped in etw.GUID("{...}").

    import etw

def some_func():
    # define capture provider info
    providers = [etw.ProviderInfo('Some Provider', etw.GUID("{11111111-1111-1111-1111-111111111111}"))]

    # create instance of ETW and start capture
    with etw.ETW(providers=providers, event_callback=etw.on_event_callback):
        # run capture
        etw.run('etw')

  4. Control ETW capture manually with start() and stop()

    master

    If you need more control over the timing of the capture (e.g., waiting for a specific duration in between), you can instantiate the etw.ETW class and call .start() and .stop() methods explicitly.

    import time
import etw

def some_func():
    # define capture provider info
    providers = [etw.ProviderInfo('Some Provider', etw.GUID("{11111111-1111-1111-1111-111111111111}"))]
    # create instance of ETW class
    job = etw.ETW(providers=providers, event_callback=lambda x: print(x))
    # start capture
    job.start()

    # wait some time
    time.sleep(5)

    # stop capture
    job.stop()