eventlog

package
v0.0.0-...-35e21f9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 20, 2024 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Rendered for windows/amd64

Overview

Package eventlog provides an interface to the Windows Event Log.

This package is a companion package to github.com/google/winops/tree/master/winlog/wevtapi. The wevtapi package provides the low-level eventlog API and some of the API constants. While wevtapi can be used directly for event log interactions, this package aims to make common event log operations simpler and more organic for the typical user.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Render 

func Render(fragment Fragment, flag uint32) (string, error)

Render renders a fragment (bookmark or event) as an XML string.

This function renders the entire fragment as XML. To render only specific elements of the event, use RenderValues.

Flags can be either EvtRenderEventValues or EvtRenderEventXml.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtrender

func UpdateBookmark 

func UpdateBookmark(bookmark Bookmark, event Event) error

UpdateBookmark updates a bookmark with information that identifies the specified event.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtupdatebookmark

Types

type Bookmark 

type Bookmark Handle

A Bookmark is a Handle returned by CreateBookmark

func CreateBookmark 

func CreateBookmark(bookmark string) (Bookmark, error)

CreateBookmark creates a bookmark that identifies an event in a channel.

func (*Bookmark) Close 

func (h *Bookmark) Close()

Close releases a Bookmark.

type Channel 

type Channel struct {
	Name string
}

Channel represents an event log channel.

type ChannelConfig 

type ChannelConfig Handle

ChannelConfig represents a handle to a Channel's configuration.

Use Session.OpenChannelConfig to obtain a ChannelConfig.

func (*ChannelConfig) Close 

func (cc *ChannelConfig) Close()

Close releases a ChannelConfig.

func (*ChannelConfig) GetProperty 

func (cc *ChannelConfig) GetProperty(propertyID wevtapi.EvtChannelConfigPropertyID) (EvtVariant, error)

GetProperty allows you to read a channel config's properties.

PropertyID must be a wevtapi.EvtChannelConfigPropertyID.

Results are returned as an EvtVariant with the corresponding property type populated.

Example: 

  p, err = cc.GetProperty(wevtapi.EvtChannelConfigOwningPublisher)
	 if err != nil {
	   return err
	 }
  fmt.Println(p.Data.StringVal)

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtgetchannelconfigproperty

type Event 

type Event Handle

An Event is a Handle to an event.

func (*Event) Close 

func (e *Event) Close()

Close releases an Event.

func (*Event) Format 

func (e *Event) Format(pub PublisherMetadata, messageID uint32, flags uint32) (string, error)

Format formats a message string.

MessageID is only set if using the EvtFormatMessageId flag. The ID is obtained using GetPublisherMetadataProperty. Set to zero if unused.

Flags should be one of the EVT_FORMAT_MESSAGE_FLAGS from wevtapi.

This method does not support supplying insertion values.

Example (evt is an open Event from the Openssh channel): 

  pub, err := eventlog.LocalSession().OpenPublisherMetadata("Openssh", "", 2057)
  if err != nil {
	   return err
	 }
	 defer pub.Close()
	 out, err := evt.Format(pub, 0, wevtapi.EvtFormatMessageXml)
	 if err != nil {
		 return err
	 }

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtformatmessage

func (*Event) Handle 

func (e *Event) Handle() windows.Handle

Handle returns the event handle.

type EventGenerator 

type EventGenerator interface {
	Handle() windows.Handle
}

An EventGenerator provides a handle to a query or subscription that may yield events.

type EventSet 

type EventSet struct {
	Events []Event
	Count  uint32
}

An EventSet holds one or more event handles.

Close() must be called to release the event handles when finished.

func Next 

func Next(handle EventGenerator, count uint32, timeout *time.Duration) (EventSet, error)

Next gets the next event(s) returned by a query or subscription.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtnext

func (*EventSet) Close 

func (e *EventSet) Close()

Close releases all events in the EventSet.

type EvtRenderContextFlags 

type EvtRenderContextFlags uint32

EvtRenderContextFlags specify which types of values to render from a given event.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/ne-winevt-evt_render_context_flags 

const (
	// EvtRenderContextValues renders specific properties from the event.
	EvtRenderContextValues EvtRenderContextFlags = iota
	// EvtRenderContextSystem renders the system properties under the System element.
	EvtRenderContextSystem
	// EvtRenderContextUser renders all user-defined properties under the UserData or EventData element.
	EvtRenderContextUser
)

type EvtVariant 

type EvtVariant struct {
	Count uint32
	Type  EvtVariantType
	Data  EvtVariantData
}

EvtVariant (EVT_VARIANT) contains event data or property values.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/ns-winevt-evt_variant

func RenderValues 

func RenderValues(renderCtx RenderContext, fragment Fragment) ([]EvtVariant, error)

RenderValues renders specific elements from a fragment (event).

You must supply a RenderContext from CreateRenderContext. The RenderContext determines which values are rendered from the fragment.

The rendered events are returned by Windows as variants (EVT_VARIANT) in a wide variety of types. We do our best to cast these into Go types, and return the results encapsulated in an EvtVariantData. EvtVariantData holds all possible types, but only the rendered value should be non-nil on return. The EvtVariant.Type field will indicate which of the EvtVariantData fields should hold the rendered data.

For example, rendering a string fragment successfully should return: 

EvtVariant {
	Type: EvtVarTypeString
	Data: EvtVariantData {
		...
		StringVal: "my rendered string"
		...
	}
}

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtrender Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/ns-winevt-evt_variant

type EvtVariantData 

type EvtVariantData struct {
	BooleanVal    bool
	SByteVal      int8
	Int16Val      int16
	Int32Val      int32
	Int64Val      int64
	ByteVal       uint8
	UInt16Val     uint16
	UInt32Val     uint32
	UInt64Val     uint64
	SingleVal     float32
	DoubleVal     float64
	FileTimeVal   windows.Filetime
	SysTimeVal    windows.Systemtime
	GuidVal       windows.GUID
	StringVal     string
	AnsiStringVal string
	BinaryVal     byte
	SidVal        windows.SID
	SizeTVal      uint32
	BooleanArr    *[]bool
	SByteArr      *[]int8
	Int16Arr      *[]int16
	Int32Arr      *[]int32
	Int64Arr      *[]int64
	ByteArr       *[]uint16
	UInt16Arr     *[]uint16
	UInt32Arr     *[]uint32
	UInt64Arr     *[]uint64
	SingleArr     *[]float32
	DoubleArr     *[]float64
	FileTimeArr   *[]windows.Filetime
	SysTimeArr    *[]windows.Systemtime
	GuidArr       *[]windows.GUID
	StringArr     *[]string
	AnsiStringArr *[]string
	SidArr        *[]windows.SID
	SizeTArr      *[]uint32
	EvtHandleVal  windows.Handle
	XmlVal        string
	XmlValArr     *[]string
}

EvtVariantData models the union inside of the EVT_VARIANT structure.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/ns-winevt-evt_variant

type EvtVariantType 

type EvtVariantType uint32

EvtVariantType (EVT_VARIANT_TYPE) defines the possible data types of a EVT_VARIANT data item.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/ne-winevt-evt_variant_type 

const (
	EvtVarTypeNull EvtVariantType = iota
	EvtVarTypeString
	EvtVarTypeAnsiString
	EvtVarTypeSByte
	EvtVarTypeByte
	EvtVarTypeInt16
	EvtVarTypeUInt16
	EvtVarTypeInt32
	EvtVarTypeUInt32
	EvtVarTypeInt64
	EvtVarTypeUInt64
	EvtVarTypeSingle
	EvtVarTypeDouble
	EvtVarTypeBoolean
	EvtVarTypeBinary
	EvtVarTypeGuid
	EvtVarTypeSizeT
	EvtVarTypeFileTime
	EvtVarTypeSysTime
	EvtVarTypeSid
	EvtVarTypeHexInt32
	EvtVarTypeHexInt64
	EvtVarTypeEvtHandle
	EvtVarTypeEvtXml
)

type Fragment 

type Fragment interface {
	Handle() windows.Handle
}

Fragment describes a renderable fragment; an event or to a bookmark.

type Handle 

type Handle struct {
	// contains filtered or unexported fields
}

Handle maps a handle to an event log resource (EVT_HANDLE). Close() must be called to release the handle.

Note that the order in which handles are closed may matter. Parent handles should not be closed until all uses of the handles (queries, etc) are complete.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtclose

type PublisherMetadata 

type PublisherMetadata Handle

PublisherMetadata is a Handle which tracks provider metadata.

func (*PublisherMetadata) Close 

func (h *PublisherMetadata) Close()

Close releases a RenderContext.

type RawVariant 

type RawVariant struct {
	Data  uint64
	Count uint32
	Type  uint32
}

RawVariant is like EvtVariant but holds the raw, un-typed data in the Data field.

type RenderContext 

type RenderContext Handle

A RenderContext is a Handle which tracks a Context as returned by EvtCreateRenderContext.

func CreateRenderContext 

func CreateRenderContext(flags EvtRenderContextFlags, valuePaths *[]string) (RenderContext, error)

CreateRenderContext creates a context that specifies the information in the event that you want to render.

The RenderContext is used to obtain only a subset of event data when querying events. Without a RenderContext, the entirety of the log data will be returned.

Passing one of EvtRenderContextSystem or EvtRenderContextUser (with valuePaths nil) will render all properties under the corresponding element (System or User). Passing EvtRenderContextValues along with a list of valuePaths allows the caller to obtain individual event elements. valuePaths must be well formed XPath expressions. See the documentation for EvtCreateRenderContext and EVT_RENDER_CONTEXT_FLAGS for more detail.

Example, rendering all System values: 

eventlog.CreateRenderContext(eventlog.EvtRenderContextSystem, nil)

Example, rendering specific values: 

eventlog.CreateRenderContext(eventlog.EvtRenderContextValues, &[]string{
		"Event/System/TimeCreated/@SystemTime", "Event/System/Provider/@Name"})

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtcreaterendercontext

func (*RenderContext) Close 

func (h *RenderContext) Close()

Close releases a RenderContext.

type ResultSet 

type ResultSet Handle

A ResultSet is a Handle returned by a Query or Subscription

func (*ResultSet) Close 

func (rs *ResultSet) Close()

Close releases a ResultSet.

func (*ResultSet) Handle 

func (rs *ResultSet) Handle() windows.Handle

Handle returns the event handle.

func (*ResultSet) Next 

func (rs *ResultSet) Next(count uint32, timeout *time.Duration) (EventSet, error)

Next is a helper that calls eventlog.Next() for ResultSets.

type Session 

type Session Handle

A Session is a Handle returned by OpenSession

func LocalSession 

func LocalSession() *Session

LocalSession returns a session object that can be used for queries against the local system event log.

func (*Session) AvailableChannels 

func (s *Session) AvailableChannels() ([]Channel, error)

AvailableChannels returns a slice of channels registered on the system.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtopenchannelenum Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtnextchannelpath

func (*Session) AvailablePublishers 

func (s *Session) AvailablePublishers() ([]string, error)

AvailablePublishers returns a slice of publishers registered on the system.

func (*Session) ClearLog 

func (s *Session) ClearLog(channelPath string, targetFilePath string) error

ClearLog removes all events from the specified channel.

If targetFilePath is non-empty, the contents of the channel will be exported to a file before clearing. If set to an empty string, the content of the channel will not be saved.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtclearlog

func (*Session) Close 

func (s *Session) Close()

Close releases a Session.

func (*Session) ExportLog 

func (s *Session) ExportLog(path string, query string, targetFilePath string, flags uint32) error

ExportLog copies events from the specified channel or log file and writes them to the target log file.

Path should be supplied the name of the channel or the full path to a log file that contains the events that you want to export.

Query should be supplied a query that specifies the types of events that you want to export, including xpath and structured xml.

TargetFilePath should be supplied the full path to the target log file that will receive the events.

Flags should be one or more of the EVT_EXPORTLOG_FLAGS from wevtapi.

Example: 

s.ExportLog("Windows Powershell", "*", "export.evtx", wevtapi.EvtExportLogChannelPath|wevtapi.EvtExportLogOverwrite)

Ref: https://learn.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtexportlog

func (*Session) OpenChannelConfig 

func (s *Session) OpenChannelConfig(logID string) (ChannelConfig, error)

OpenChannelConfig allows you to read and modify channel config properties.

You must call Close() on the resulting ChannelConfig when finished.

Example: 

s.OpenChannelConfig("Microsoft-Windows-DriverFrameworks-UserMode/Operational")

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtopenchannelconfig

func (*Session) OpenPublisherMetadata 

func (s *Session) OpenPublisherMetadata(publisherID string, logFilePath string, locale uint32) (PublisherMetadata, error)

OpenPublisherMetadata gets a handle that you use to read the specified provider's metadata.

Publisher IDs can be enumerated by calling Session.AvailablePublishers.

logFilePath is only needed if the provider is not on the local computer; otherwise leave blank.

Locale can be set to an ID value from https://docs.microsoft.com/en-us/previous-versions/windows/embedded/ms912047(v=winembedded.10). Leave as zero to use the locale of the running thread.

Call Close() on the PublisherMetadata once complete.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtopenpublishermetadata

func (*Session) Query 

func (s *Session) Query(path string, query string, flags uint32) (ResultSet, error)

Query runs a query to retrieve events from a channel or log file that match the specified query criteria.

Session is only required for remote connections; leave as nil for the local log. Flags can be any of wevtapi.EVT_QUERY_FLAGS.

The session handle must remain open until all subsequent processing on the query results have completed. Call Close() once complete.

Example: 

	 conn, err := eventlog.LocalSession().Query("Windows Powershell", "*", wevtapi.EvtQueryReverseDirection)
	 if err != nil {
    return err
	 }
	 defer conn.Close()

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtquery

func (*Session) Subscribe 

func (s *Session) Subscribe(signalEvent *windows.Handle, channelPath string, query string, bookmark *Bookmark, flags uint32) (Subscription, error)

Subscribe creates a subscription that will receive current and/or future events from a channel or log file which match the specified query criteria.

This method uses SignalEvent rather than Callback for notifying of new events. You may create and provide a custom signal event using windows.CreateEvent. If signalEvent is left as nil, a default event will be created for you. In either case, the event is returned inside the resulting Subscription. This subscription model is referred to as a "pull subscription", as you must watch for the signal events to arrive, and use Next to obtain the results.

channelPath and query can be used in multiple combinations, including xpath and structured xml. See the API documentation for details.

Bookmark should be supplied if using the EvtSubscribeStartAfterBookmark flag. Otherwise it should be left as nil.

Flags should be one or more of the EVT_SUBSCRIBE_FLAGS from wevtapi.

You must call Close() on the resulting Subscription when finished.

Ref: https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtsubscribe

type Subscription 

type Subscription struct {
	SignalEvent windows.Handle
	// contains filtered or unexported fields
}

Subscription tracks an event subscription created by Session.Subscribe.

func (*Subscription) Close 

func (s *Subscription) Close()

Close releases a Subscription.

func (*Subscription) Handle 

func (s *Subscription) Handle() windows.Handle

Handle returns the subscription handle.

func (*Subscription) Next 

func (s *Subscription) Next(count uint32, timeout *time.Duration) (EventSet, error)

Next attempts to get the next available events for the subscription.

func (*Subscription) WaitForSignal 

func (s *Subscription) WaitForSignal(timeout time.Duration) (bool, error)

WaitForSignal waits for new events to arrive via the SignalEvent. Returns true if the event was signalled before the timeout expired. Timeout must be between 0 and 2^32us.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.