etw

README

etw

etw is a Go-package that allows you to receive Event Tracing for Windows (ETW) events in go code.

etw allows you to process events from new TraceLogging providers as well as from classic (aka EventLog) providers, so you could actually listen to anything you can see in Event Viewer window.

Fork info

This is a fork of https://github.com/bi-zone/etw that adds some functionality, especially:

• Looking up (manifest) providers at runtime
• Building without CGO
• Filtering on ETW sessions
• Registering for multiple providers in a single ETW session

Docs

Package reference is available at https://pkg.go.dev/github.com/secDre4mer/etw

Examples are located in examples folder.

Usage

package main

import (
	"log"
	"os"
	"os/signal"
	"sync"

	"github.com/SEKOIA-IO/etw"
)

func main() {
	session, err := etw.NewSession()
	if err != nil {
		log.Fatalf("Failed to create etw session: %s", err)
	}

	// Subscribe to Microsoft-Windows-DNS-Client
	dnsClient, err := etw.LookupProvider("Microsoft-Windows-DNS-Client")
	if err != nil {
		log.Fatalf("Failed to find DNS client provider: %s", err)
    }
	if err := session.AddProvider(dnsClient.Guid); err != nil {
		log.Fatalf("Failed to register for provider: %v", err)
	}

	// Wait for "DNS query request" events to log outgoing DNS requests.
	cb := func(e *etw.Event) {
		if e.Header.ID != 3006 {
			return
		}
		if data, err := e.EventProperties(); err == nil && data["QueryType"] == "1" {
			log.Printf("PID %d just queried DNS for domain %v", e.Header.ProcessID, data["QueryName"])
		}
	}

	// `session.Process` blocks until `session.Close()`, so start it in routine.
	var wg sync.WaitGroup
	wg.Add(1)
	go func() {
		if err := session.Process(cb); err != nil {
			log.Printf("[ERR] Got error processing events: %s", err)
		}
		wg.Done()
	}()

	// Trap cancellation.
	sigCh := make(chan os.Signal, 1)
	signal.Notify(sigCh, os.Interrupt)
	<-sigCh

	if err := session.Close(); err != nil {
		log.Printf("[ERR] Got error closing the session: %s", err)
	}
	wg.Wait()
}

More sophisticated examples can be found in examples folder.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Documentation

Index

• type CompareOperation
• type EventDescriptor
• type EventFieldType
• type EventFilter
• type EventFilterDescriptor
• type EventFilterType
• type EventIdFilter
  • func (e EventIdFilter) EventFilterDescriptor() (EventFilterDescriptor, error)
  • func (e EventIdFilter) Merge(other EventFilter) (EventFilter, error)
  • func (e EventIdFilter) Type() EventFilterType
• type EventPayloadCompare
• type EventPayloadFilter
  • func (e EventPayloadFilter) EventFilterDescriptor() (EventFilterDescriptor, error)
  • func (EventPayloadFilter) Merge(filter EventFilter) (EventFilter, error)
  • func (EventPayloadFilter) Type() EventFilterType
• type Provider
  • func ListProviders() ([]Provider, error)
  • func LookupProvider(name string) (Provider, error)
  • func (p Provider) ListChannels() ([]ProviderField, error)
  • func (p Provider) ListEvents() ([]EventDescriptor, error)
  • func (p Provider) ListKeywords() ([]ProviderField, error)
  • func (p Provider) ListLevels() ([]ProviderField, error)
  • func (p Provider) QueryField(fieldValue uint64, fieldType EventFieldType) ([]ProviderField, error)
  • func (p Provider) QueryOpcode(taskValue uint16, opcodeValue uint8) (ProviderField, error)
  • func (p Provider) QueryTask(taskValue uint16) (ProviderField, error)
• type ProviderField

Types

type CompareOperation

type CompareOperation uint16

const (
	CompareIntegerEqual CompareOperation = iota
	CompareIntegerNotEqual
	CompareIntegerLessOrEqual
	CompareIntegerGreater
	CompareIntegerLess
	CompareIntegerGreatorOrEqual
	CompareIntegerBetween
	CompareIntegerNotBetween
	CompareIntegerModulo
)

const (
	CompareStringContains    CompareOperation = 20
	CompareStringNotContains CompareOperation = 21
	CompareStringEquals      CompareOperation = 30
	CompareStringNotEquals   CompareOperation = 31
)

type EventDescriptor

type EventDescriptor struct {
	ID      uint16
	Version uint8
	Channel uint8
	Level   uint8
	OpCode  uint8
	Task    uint16
	Keyword uint64
}

EventDescriptor contains low-level metadata that defines received event. Most of fields could be used to refine events filtration.

For detailed information about fields values refer to EVENT_DESCRIPTOR docs: https://docs.microsoft.com/ru-ru/windows/win32/api/evntprov/ns-evntprov-event_descriptor

type EventFieldType

type EventFieldType uint32

const (
	EventKeywordInformation EventFieldType = iota
	EventLevelInformation
	EventChannelInformation
	EventTaskInformation
	EventOpcodeInformation
)

type EventFilter

type EventFilter interface {
	EventFilterDescriptor() (EventFilterDescriptor, error)
	Type() EventFilterType
	Merge(filter EventFilter) (EventFilter, error)
}

type EventFilterDescriptor

type EventFilterDescriptor struct {
	Descriptor eventFilterDescriptorC
	Close      func() error
}

type EventFilterType

type EventFilterType uint32

type EventIdFilter

type EventIdFilter struct {
	// The Event IDs that the filter should look for
	EventIds []uint16
	// True for a filter that accepts only the given Event IDs, False for a filter that rejects the given Event IDs
	PositiveFilter bool
}

EventIdFilter is a simple filter that filters by Event ID. Either a positive filter can be defined that allows only specific Event IDs or a negative filter that disallows specific Event IDs. Specifying both types is not allowed.

func (EventIdFilter) EventFilterDescriptor

func (e EventIdFilter) EventFilterDescriptor() (EventFilterDescriptor, error)

func (EventIdFilter) Merge

func (e EventIdFilter) Merge(other EventFilter) (EventFilter, error)

func (EventIdFilter) Type

func (e EventIdFilter) Type() EventFilterType

type EventPayloadCompare

type EventPayloadCompare struct {
	Field     string
	Value     string
	Operation CompareOperation
}

type EventPayloadFilter

type EventPayloadFilter struct {
	FilteredProvider   windows.GUID
	FilteredDescriptor EventDescriptor
	Comparisons        []EventPayloadCompare
	AnyMatches         bool
}

func (EventPayloadFilter) EventFilterDescriptor

func (e EventPayloadFilter) EventFilterDescriptor() (EventFilterDescriptor, error)

func (EventPayloadFilter) Merge

func (EventPayloadFilter) Merge(filter EventFilter) (EventFilter, error)

func (EventPayloadFilter) Type

func (EventPayloadFilter) Type() EventFilterType

type Provider

type Provider struct {
	Name string
	Guid windows.GUID
}

func ListProviders

func ListProviders() ([]Provider, error)

func LookupProvider

func LookupProvider(name string) (Provider, error)

func (Provider) ListChannels

func (p Provider) ListChannels() ([]ProviderField, error)

func (Provider) ListEvents

func (p Provider) ListEvents() ([]EventDescriptor, error)

func (Provider) ListKeywords

func (p Provider) ListKeywords() ([]ProviderField, error)

func (Provider) ListLevels

func (p Provider) ListLevels() ([]ProviderField, error)

func (Provider) QueryField

func (p Provider) QueryField(fieldValue uint64, fieldType EventFieldType) ([]ProviderField, error)

func (Provider) QueryOpcode

func (p Provider) QueryOpcode(taskValue uint16, opcodeValue uint8) (ProviderField, error)

func (Provider) QueryTask

func (p Provider) QueryTask(taskValue uint16) (ProviderField, error)

type ProviderField

type ProviderField struct {
	Name        string
	Description string
	ID          uint64
}