eventwatcher

README

EventWatcher

Overview

EventWatcher is an open-source library designed for monitoring Windows Event Logs in real-time. It provides a robust and efficient solution for tracking and reacting to system events, application logs, and other important event sources. This library is particularly useful for developers and system administrators who need to monitor event logs for debugging, auditing, and system management purposes.

Usage

To use the EventWatcher library, you need to:

1. Create an EventNotifier instance.
2. Add event watchers for the logs you are interested in.
3. Listen for event data on the EventLogChannel.
4. Ensure a graceful shutdown by properly closing the EventNotifier.

Installation

To install the EventWatcher library, run:

go get github.com/auuunya/eventwatcher

Example

package main

import (
	"github.com/auuunya/eventwatcher"
)

func main() {
	ctx := context.Background()
	notify := eventwatcher.NewEventNotifier(ctx)
	defer notify.Close()

	channels := []string{"Application", "System", "Microsoft-Windows-Kernel-Dump/Operational"}
	for _, channel := range channels {
		err := notify.AddWatcher(channel)
		if err != nil {
			continue
		}
	}

	go func() {
		for ch := range notify.EventLogChannel {
			fmt.Printf("event entry: %v\n", ch)
		}
	}()

	quit := make(chan os.Signal, 1)
	signal.Notify(quit, syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM)
	<-quit
}

Windows powershell add event

Write-EventLog -LogName "Application" -Source "TestSource" -EventID 1 -EntryType Information -Message "Application Test Info"

Windows cmd add event

eventcreate /ID 1 /L APPLICATION /T INFORMATION  /SO MYEVENTSOURCE /D "Test Application Infomation"

Cross-platform support

• Windows: Uses native Windows Event Log APIs (original behavior). Windows-specific tests and implementations are build-tagged with //go:build windows.
• macOS / Linux: A lightweight file-watching implementation using fsnotify is provided for Unix-like systems. On these platforms, call AddWatcher(path) where path is a file path (writing to the file will emit an event).
• Notes: On non-Windows platforms, Windows-specific APIs return not-implemented errors; use the Unix watcher for most cross-platform needs.

Running tests & profiling

• Run all tests: go test ./...
• Run Unix watcher test (macOS/Linux): go test -run TestEventWatcherUnixFile -v
• Run memory check: go test -run TestMemSpike -v (this logs runtime.MemStats before/after watcher start).

Contribution

Contributions are welcome! Feel free to open issues or submit pull requests on the GitHub repository.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Documentation

Index

• Constants
• func CloseEventLog(handle uintptr) error
• func CloseHandle(handle uintptr) error
• func CreateEvent(eventAttributes *uintptr, manualReset, initialState uint32, name *uint16) (uintptr, error)
• func DeregisterEventSource(log uintptr) error
• func EventLogRecordNumber(handle uintptr) (uint32, error)
• func EvtClose(handle uintptr) error
• func EvtNextChannelPath(handle uintptr) ([]string, error)
• func EvtOpenChannelEnum(session uintptr) (uintptr, error)
• func FormatContent(buf []byte) string
• func FormatMessage(errorCode uint32) string
• func LookupAccountSid(buf []byte, sidlen, sidoffset uint32) (string, string, error)
• func NotifyChangeEventLog(handle, event uintptr) error
• func OpenEventLog(name string) (uintptr, error)
• func ReadEventLog(handle uintptr, flags, offset uint32) ([]byte, error)
• func RegisterEventSource(uncServerName, sourceName *uint16) (handle uintptr, err error)
• func ReportEvent(log uintptr, etype uint16, category uint16, eventID uint32, userSid *uintptr, ...) error
• func ResetEvent(handle uintptr) error
• func SetEvent(handle uintptr) error
• func WaitForMultipleObjects(handles []uintptr, waitAll bool, waitMilliseconds uint32) (event uint32, err error)
• type EventEntry
• type EventLogRecord
  • func ParseEventLogData(buf []byte) *EventLogRecord
  • func ParserEventLogData(buf []byte) (*EventLogRecord, error)
• type EventNotifier
  • func NewEventNotifier(ctx context.Context) *EventNotifier
  • func (en *EventNotifier) AddWatcher(name string) error
  • func (en *EventNotifier) Close()
  • func (en *EventNotifier) GetWatcher(name string) (*EventWatcher, error)
  • func (en *EventNotifier) RemoveWatcher(name string) error
• type EventWatcher
  • func NewEventWatcher(ctx context.Context, name string, eventChan chan *EventEntry) *EventWatcher
  • func (ew *EventWatcher) Close()
  • func (ew *EventWatcher) CloseHandles() error
  • func (ew *EventWatcher) Init() error
  • func (ew *EventWatcher) Listen()
• type SID_NAME_USE

Constants

const (
	// Use uintptr for cross-platform handle representation.
	InvalidHandle = uintptr(0)

	ERROR_HANDLE_EOF          syscall.Errno = 38
	ERROR_INSUFFICIENT_BUFFER syscall.Errno = 122
	ERROR_NO_MORE_ITEMS       syscall.Errno = 259
	NO_ERROR                                = 0
)

const (
	EVENTLOG_SUCCESS          = 0x0000
	EVENTLOG_ERROR_TYPE       = 0x0001
	EVENTLOG_WARNING_TYPE     = 0x0002
	EVENTLOG_INFORMATION_TYPE = 0x0004
	EVENTLOG_AUDIT_SUCCESS    = 0x0008
	EVENTLOG_AUDIT_FAILURE    = 0x0010
)

const (
	// https://learn.microsoft.com/zh-cn/windows/win32/api/winbase/nf-winbase-readeventloga
	EVENTLOG_SEEK_READ       = 0x0002
	EVENTLOG_SEQUENTIAL_READ = 0x0001

	EVENTLOG_FORWARDS_READ  = 0x0004
	EVENTLOG_BACKWARDS_READ = 0x0008
)

Functions

func CloseEventLog

func CloseEventLog(handle uintptr) error

func CloseHandle

func CloseHandle(handle uintptr) error

func CreateEvent

func CreateEvent(
	eventAttributes *uintptr,
	manualReset, initialState uint32,
	name *uint16,
) (uintptr, error)

func DeregisterEventSource

func DeregisterEventSource(log uintptr) error

func EventLogRecordNumber

func EventLogRecordNumber(handle uintptr) (uint32, error)

func EvtClose

func EvtClose(handle uintptr) error

func EvtNextChannelPath

func EvtNextChannelPath(handle uintptr) ([]string, error)

func EvtOpenChannelEnum

func EvtOpenChannelEnum(session uintptr) (uintptr, error)

Non-Windows stubs for channel enumeration APIs.

func FormatContent

func FormatContent(buf []byte) string

func FormatMessage

func FormatMessage(errorCode uint32) string

func LookupAccountSid

func LookupAccountSid(buf []byte, sidlen, sidoffset uint32) (string, string, error)

func NotifyChangeEventLog

func NotifyChangeEventLog(handle, event uintptr) error

func OpenEventLog

func OpenEventLog(name string) (uintptr, error)

func ReadEventLog

func ReadEventLog(handle uintptr, flags, offset uint32) ([]byte, error)

func RegisterEventSource

func RegisterEventSource(uncServerName, sourceName *uint16) (handle uintptr, err error)

func ReportEvent

func ReportEvent(log uintptr, etype uint16, category uint16, eventID uint32, userSid *uintptr, strings []string, binaryData []byte) error

func ResetEvent

func ResetEvent(handle uintptr) error

func SetEvent

func SetEvent(handle uintptr) error

func WaitForMultipleObjects

func WaitForMultipleObjects(
	handles []uintptr,
	waitAll bool,
	waitMilliseconds uint32,
) (event uint32, err error)

Types

type EventEntry

type EventEntry struct {
	Name   string  `json:"name"`
	Handle uintptr `json:"handle"`
	Buffer []byte  `json:"buffer"`
}

type EventLogRecord

type EventLogRecord struct{}

func ParseEventLogData

func ParseEventLogData(buf []byte) *EventLogRecord

func ParserEventLogData

func ParserEventLogData(buf []byte) (*EventLogRecord, error)

type EventNotifier

type EventNotifier struct {
	EventLogChannel chan *EventEntry
	// contains filtered or unexported fields
}

EventNotifier manages a collection of EventWatchers.

func NewEventNotifier

func NewEventNotifier(ctx context.Context) *EventNotifier

NewEventNotifier creates a new EventNotifier instance.

func (*EventNotifier) AddWatcher

func (en *EventNotifier) AddWatcher(name string) error

AddWatcher adds a new EventWatcher to the EventNotifier.

func (*EventNotifier) Close

func (en *EventNotifier) Close()

Close shuts down all EventWatchers and waits for them to exit.

func (*EventNotifier) GetWatcher

func (en *EventNotifier) GetWatcher(name string) (*EventWatcher, error)

GetWatcher retrieves an EventWatcher by name.

func (*EventNotifier) RemoveWatcher

func (en *EventNotifier) RemoveWatcher(name string) error

RemoveWatcher removes an EventWatcher from the EventNotifier.

type EventWatcher

type EventWatcher struct {
	Name string
	// contains filtered or unexported fields
}

func NewEventWatcher

func NewEventWatcher(ctx context.Context, name string, eventChan chan *EventEntry) *EventWatcher

func (*EventWatcher) Close

func (ew *EventWatcher) Close()

Close stops the watcher.

func (*EventWatcher) CloseHandles

func (ew *EventWatcher) CloseHandles() error

Close handles cleans up resources for the watcher.

func (*EventWatcher) Init

func (ew *EventWatcher) Init() error

Init sets up fsnotify watcher for the provided file path.

func (*EventWatcher) Listen

func (ew *EventWatcher) Listen()

Listen monitors the fsnotify watcher and emits file contents on write events.

type SID_NAME_USE

type SID_NAME_USE uint32

const (
	// https://learn.microsoft.com/zh-cn/windows/win32/api/winnt/ne-winnt-sid_name_use
	SidTypeUser SID_NAME_USE = iota + 1
	SidTypeGroup
	SidTypeDomain
	SidTypeAlias
	SidTypeWellKnownGroup
	SidTypeDeletedAccount
	SidTypeInvalid
	SidTypeUnknown
	SidTypeComputer
	SidTypeLabel
	SidTypeLogonSession
)