wineventlog

package
v3.8.17 Latest Latest
Warning

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

Go to latest
Published: Feb 16, 2023 License: BSD-2-Clause, Apache-2.0, Apache-2.0 Imports: 11 Imported by: 0

README

This code started its life as a direct lift of the code at https://github.com/elastic/beats/tree/master/winlogbeat/sys/wineventlog
which is governed by the Apache2.0 license.  We had to lift the code due to the vendoring that the elastic respository enforces.

But now it's so heavily modified it's basically its own beast, but still governed under the Apache2.0 license.

Abandon hope all ye who enter here, the Windows eventlog system is a patchwork of hellfire, brimestone, UTF-16, and XML.

Documentation

Overview

Package wineventlog provides access to the Windows Event Log API used in all versions of Windows since Vista (i.e. Windows 7+ and Windows Server 2008+). This is distinct from the Event Logging API that was used in Windows XP, Windows Server 2003, and Windows 2000.

Index

Constants

View Source
const (
	ERROR_INSUFFICIENT_BUFFER syscall.Errno = 122
	ERROR_NO_MORE_ITEMS       syscall.Errno = 259
	//ERROR_TIMEOUT                         syscall.Errno = 2
	ERROR_NONE_MAPPED                     syscall.Errno = 1332
	RPC_S_INVALID_BOUND                   syscall.Errno = 1734
	ERROR_INVALID_OPERATION               syscall.Errno = 4317
	ERROR_EVT_MESSAGE_NOT_FOUND           syscall.Errno = 15027
	ERROR_EVT_MESSAGE_ID_NOT_FOUND        syscall.Errno = 15028
	ERROR_EVT_UNRESOLVED_VALUE_INSERT     syscall.Errno = 15029
	ERROR_EVT_UNRESOLVED_PARAMETER_INSERT syscall.Errno = 15030
)

Event log error codes. https://msdn.microsoft.com/en-us/library/windows/desktop/ms681382(v=vs.85).aspx

Variables

View Source
var (
	// ErrorEvtVarTypeNull is an error that means the content of the EVT_VARIANT
	// data is null.
	ErrorEvtVarTypeNull = errors.New("null EVT_VARIANT data")
)

Errors

View Source
var EventLevelToString = map[EventLevel]string{
	EVENTLOG_LOGALWAYS_LEVEL:   "Information",
	EVENTLOG_INFORMATION_LEVEL: "Information",
	EVENTLOG_CRITICAL_LEVEL:    "Critical",
	EVENTLOG_ERROR_LEVEL:       "Error",
	EVENTLOG_WARNING_LEVEL:     "Warning",
	EVENTLOG_VERBOSE_LEVEL:     "Verbose",
}

Mapping of event levels to their string representations.

Functions

func Channels

func Channels() ([]string, error)

Channels returns a list of channels that are registered on the computer.

func Close

func Close(h EvtHandle) error

Close closes an EvtHandle.

func EvtGetChannelConfigProperty

func EvtGetChannelConfigProperty(handle EvtHandle, id EvtChannelConfigPropertyId) (buff []byte, err error)

EvtGetChannelConfigProperty queries a channel configuration variable given a handle to the channel configuration

func EvtGetLogInfo

func EvtGetLogInfo(session EvtHandle, id EvtLogPropertyId) (buff []byte, err error)

EvtGetLogInfo executes the GetLogInfo syscall to provide information about an open log handle

func EvtSeek

func EvtSeek(resultSet EvtHandle, position int64, bookmark EvtHandle, flags EvtSeekFlag) error

EvtSeek seeks to a specific event in a query result set.

func FormatEventString

func FormatEventString(
	messageFlag EvtFormatMessageFlag,
	eventHandle EvtHandle,
	publisher string,
	publisherHandle EvtHandle,
	lang uint32,
	buffer []byte,
	out io.Writer,
) error

FormatEventString formats part of the event as a string. messageFlag determines what part of the event is formatted as as string. eventHandle is the handle to the event. publisher is the name of the event's publisher. publisherHandle is a handle to the publisher's metadata as provided by EvtOpenPublisherMetadata. lang is the language ID. buffer is optional and if not provided it will be allocated. If the provided buffer is not large enough then an InsufficientBufferError will be returned.

func GetChannelFileCreationTime

func GetChannelFileCreationTime(ch string) (ts time.Time, err error)

func GetChannelFilePath

func GetChannelFilePath(ch string) (pth string, err error)

GetChannelFilePath queries a channel to get the full path of the file that backs it

func GetRecordIDFromBookmark

func GetRecordIDFromBookmark(bookmark EvtHandle, buff []byte, bb *bytes.Buffer) (r uint64, err error)

GetBookmarkRecordId takes a bookmark handle, renders it to XML we the parse the XML to extract the record id and hand it back

func IsAvailable

func IsAvailable() (bool, error)

IsAvailable returns true if the Windows Event Log API is supported by this operating system. If not supported then false is returned with the accompanying error.

func RenderBookmarkXML

func RenderBookmarkXML(bookmarkHandle EvtHandle, renderBuf []byte, out io.Writer) error

RenderBookmarkXML renders a bookmark as XML.

func RenderEventSimple

func RenderEventSimple(eh EvtHandle, buf []byte, out io.Writer) error

RenderEventSimple reads event data associated with an EvtHandle and renders the data using a simple XML. This function DOES NOT attempt to resolve publisher metadata nor does it use the FormatEventString functionality GRAVWELL NOTE/TODO - We have yet to see the FormatEventString call succeed it always fails in the OpenPublisherMetadata call, which fails with an error about not being able to find the specified file. The call to OpenPublisherMetdata also incurs SIGNIFICANT performance overhead, slowing rendering down a 1000 fold and taxing the host system.

func RenderEventXML

func RenderEventXML(eventHandle EvtHandle, renderBuf []byte, out io.Writer) error

RenderEventXML renders the event as XML. If the event is already rendered, as in a forwarded event whose content type is "RenderedText", then the XML will include the RenderingInfo (message). If the event is not rendered then the XML will not include the message, and in this case RenderEvent should be used.

func UTF16BytesToString

func UTF16BytesToString(b []byte) (string, int, error)

UTF16BytesToString returns a string that is decoded from the UTF-16 bytes. The byte slice must be of even length otherwise an error will be returned. The integer returned is the offset to the start of the next string with buffer if it exists, otherwise -1 is returned.

func UTF16LEBufferToUTF8Bytes added in v3.8.17

func UTF16LEBufferToUTF8Bytes(v []byte) (r []byte, err error)

UTF16LEBufferToUTF8Bytes takes UTF-16 in little endian encoding without a BOM and spits it back out as UTF8. Basically take the insanity of Windows native strings and turn it back into nice clean UTF-8, just like the way mom used to make it.

func UTF16LEBufferToUTF8Writer added in v3.8.17

func UTF16LEBufferToUTF8Writer(v []byte, out io.Writer) (err error)

func UTF16LEToUTF8 added in v3.8.17

func UTF16LEToUTF8(v []byte) (s string, err error)

UTF16LEToUTF8 wraps UTF16LEToUTF8Bytes to return a string

func UTF16LEToUTF8Bytes added in v3.8.17

func UTF16LEToUTF8Bytes(v []uint16) (r []byte)

func UpdateBookmarkFromEvent

func UpdateBookmarkFromEvent(bookmark, handle EvtHandle) error

UpdateBookmarkFromEvent Updates an existing bookmark from using an event handle This function just wraps the unexported version

func VarantString

func VarantString(buff []byte) (s string, err error)

Types

type Bookmark

type Bookmark struct {
	RecordId uint64 `xml:",attr"`
}

type BookmarkList

type BookmarkList struct {
	Bookmarks []Bookmark `xml:"Bookmark"`
}

type EventLevel

type EventLevel uint16

EventLevel identifies the six levels of events that can be logged

const (
	// Do not reorder.
	EVENTLOG_LOGALWAYS_LEVEL EventLevel = iota
	EVENTLOG_CRITICAL_LEVEL
	EVENTLOG_ERROR_LEVEL
	EVENTLOG_WARNING_LEVEL
	EVENTLOG_INFORMATION_LEVEL
	EVENTLOG_VERBOSE_LEVEL
)

EventLevel values.

func (EventLevel) String

func (et EventLevel) String() string

String returns string representation of EventLevel.

type EvtChannelConfigPropertyId

type EvtChannelConfigPropertyId uint32
const (
	EvtChannelConfigEnabled EvtChannelConfigPropertyId = iota
	EvtChannelConfigIsolation
	EvtChannelConfigType
	EvtChannelConfigOwningPublisher
	EvtChannelConfigClassicEventlog
	EvtChannelConfigAccess
	EvtChannelLoggingConfigRetention
	EvtChannelLoggingConfigAutoBackup
	EvtChannelLoggingConfigMaxSize
	EvtChannelLoggingConfigLogFilePath
	EvtChannelPublishingConfigLevel
	EvtChannelPublishingConfigKeywords
	EvtChannelPublishingConfigControlGuid
	EvtChannelPublishingConfigBufferSize
	EvtChannelPublishingConfigMinBuffers
	EvtChannelPublishingConfigMaxBuffers
	EvtChannelPublishingConfigLatency
	EvtChannelPublishingConfigClockType
	EvtChannelPublishingConfigSidType
	EvtChannelPublisherList
	EvtChannelPublishingConfigFileMax
)

EVT_CHANNEL_CONFIG_PROPERTY_ID enumeration https://docs.microsoft.com/en-us/windows/win32/api/winevt/ne-winevt-evt_channel_config_property_id

type EvtFormatMessageFlag

type EvtFormatMessageFlag uint32

EvtFormatMessageFlag defines the values that specify the message string from the event to format.

const (
	// Format the event's message string.
	EvtFormatMessageEvent EvtFormatMessageFlag = iota + 1
	// Format the message string of the level specified in the event.
	EvtFormatMessageLevel
	// Format the message string of the task specified in the event.
	EvtFormatMessageTask
	// Format the message string of the task specified in the event.
	EvtFormatMessageOpcode
	// Format the message string of the keywords specified in the event. If the
	// event specifies multiple keywords, the formatted string is a list of
	// null-terminated strings. Increment through the strings until your pointer
	// points past the end of the used buffer.
	EvtFormatMessageKeyword
	// Format the message string of the channel specified in the event.
	EvtFormatMessageChannel
	// Format the provider's message string.
	EvtFormatMessageProvider
	// Format the message string associated with a resource identifier. The
	// provider's metadata contains the resource identifiers; the message
	// compiler assigns a resource identifier to each string when it compiles
	// the manifest.
	EvtFormatMessageId
	// Format all the message strings in the event. The formatted message is an
	// XML string that contains the event details and the message strings.
	EvtFormatMessageXml
)

EVT_FORMAT_MESSAGE_FLAGS enumeration https://msdn.microsoft.com/en-us/library/windows/desktop/aa385525(v=vs.85).aspx

type EvtHandle

type EvtHandle uintptr

EvtHandle is a handle to the event log.

func CreateBookmark

func CreateBookmark() (EvtHandle, error)

CreateBookmark just creates a new empty bookmark caller must close the returned handle

func CreateBookmarkFromEvent

func CreateBookmarkFromEvent(handle EvtHandle) (EvtHandle, error)

CreateBookmarkFromEvent creates a new bookmark pointing to the given event. Close must be called on returned EvtHandle when finished with the handle.

func CreateBookmarkFromRecordID

func CreateBookmarkFromRecordID(channel string, recordID uint64) (EvtHandle, error)

CreateBookmarkFromRecordID creates a new bookmark pointing to the given recordID within the supplied channel. Close must be called on returned EvtHandle when finished with the handle.

func CreateBookmarkFromXML

func CreateBookmarkFromXML(bookmarkXML string) (EvtHandle, error)

CreateBookmarkFromXML creates a new bookmark from the serialised representation of an existing bookmark. Close must be called on returned EvtHandle when finished with the handle.

func CreateRenderContext

func CreateRenderContext(valuePaths []string, flag EvtRenderContextFlag) (EvtHandle, error)

CreateRenderContext creates a render context. Close must be called on returned EvtHandle when finished with the handle.

func EventHandles

func EventHandles(subscription EvtHandle, maxHandles int) ([]EvtHandle, error)

EventHandles reads the event handles from a subscription. It attempt to read at most maxHandles. ErrorNoMoreHandles is returned when there are no more handles available to return. Close must be called on each returned EvtHandle when finished with the handle.

func EvtOpenChannelConfig

func EvtOpenChannelConfig(path string) (handle EvtHandle, err error)

EvtOpenChannelConfig opens a handle on a channel subscription that represents the channel config

func EvtOpenLog

func EvtOpenLog(session EvtHandle, path string, flags EvtOpenLogFlag) (EvtHandle, error)

EvtOpenLog gets a handle to a channel or log file that you can then use to get information about the channel or log file.

func EvtQuery

func EvtQuery(session EvtHandle, path string, query string, flags EvtQueryFlag) (EvtHandle, error)

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

func OpenPublisherMetadata

func OpenPublisherMetadata(
	session EvtHandle,
	publisherName string,
	lang uint32,
) (EvtHandle, error)

OpenPublisherMetadata opens a handle to the publisher's metadata. Close must be called on returned EvtHandle when finished with the handle.

func Subscribe

func Subscribe(
	session EvtHandle,
	event windows.Handle,
	channelPath string,
	query string,
	bookmark EvtHandle,
	flags EvtSubscribeFlag,
) (EvtHandle, error)

Subscribe creates a new subscription to an event log channel.

type EvtLogPropertyId

type EvtLogPropertyId uint32
const (
	EvtLogCreationTime EvtLogPropertyId = iota
	EvtLogLastAccessTime
	EvtLogLastWriteTime
	EvtLogFileSize
	EvtLogAttributes
	EvtLogNumberOfLogRecords
	EvtLogOldestRecordNumber
	EvtLogFull
)

EVT_LOG_PROPERTY_ID enumeration https://docs.microsoft.com/en-us/windows/win32/api/winevt/ne-winevt-evt_log_property_id

type EvtOpenLogFlag

type EvtOpenLogFlag uint32

EvtOpenLogFlag defines the values that specify whether to open a channel or exported log file. This maps to EVT_OPEN_LOG_FLAGS in Windows.

const (
	// EvtOpenChannelPath opens a channel.
	EvtOpenChannelPath EvtOpenLogFlag = 0x1
	// EvtOpenFilePath opens an exported log file.
	EvtOpenFilePath EvtOpenLogFlag = 0x2
)

type EvtQueryFlag

type EvtQueryFlag uint32

EvtQueryFlag defines the values that specify how to return the query results and whether you are query against a channel or log file.

const (
	// EvtQueryChannelPath specifies that the query is against one or more
	// channels. The Path parameter of the EvtQuery function must specify the
	// name of a channel or NULL.
	EvtQueryChannelPath EvtQueryFlag = 0x1
	// EvtQueryFilePath specifies that the query is against one or more log
	// files. The Path parameter of the EvtQuery function must specify the full
	// path to a log file or NULL.
	EvtQueryFilePath EvtQueryFlag = 0x2
	// EvtQueryForwardDirection specifies that the events in the query result
	// are ordered from oldest to newest. This is the default.
	EvtQueryForwardDirection EvtQueryFlag = 0x100
	// EvtQueryReverseDirection specifies that the events in the query result
	// are ordered from newest to oldest.
	EvtQueryReverseDirection EvtQueryFlag = 0x200
	// EvtQueryTolerateQueryErrors specifies that EvtQuery should run the query
	// even if the part of the query generates an error (is not well formed).
	EvtQueryTolerateQueryErrors EvtQueryFlag = 0x1000
)

type EvtReadFlag added in v3.8.14

type EvtReadFlag uint32

EvtReadFlag defines flags for the operations on EventLog files

const (
	// EvtSequentialRead indicates we want to do a sequential read
	EvtSequentialRead EvtReadFlag = 1
	// EvtSeekRead indicates that we want to read directly from an offset
	EvtSeekRead EvtReadFlag = 2
	// EvtForwardsRead indicates we want to read forward
	EvtForwardsRead EvtReadFlag = 4
	// EvtBackwardsRead indicates we want to read backwards
	EvtBackwardsRead EvtReadFlag = 8
)

type EvtRenderContextFlag

type EvtRenderContextFlag uint32

EvtRenderContextFlag defines the values that specify the type of information to access from the event.

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

EVT_RENDER_CONTEXT_FLAGS enumeration https://msdn.microsoft.com/en-us/library/windows/desktop/aa385561(v=vs.85).aspx

type EvtRenderFlag

type EvtRenderFlag uint32

EvtRenderFlag defines the values that specify what to render.

const (
	// Render the event properties specified in the rendering context.
	EvtRenderEventValues EvtRenderFlag = iota
	// Render the event as an XML string. For details on the contents of the
	// XML string, see the Event schema.
	EvtRenderEventXml
	// Render the bookmark as an XML string, so that you can easily persist the
	// bookmark for use later.
	EvtRenderBookmark
)

EVT_RENDER_FLAGS enumeration https://msdn.microsoft.com/en-us/library/windows/desktop/aa385563(v=vs.85).aspx

type EvtSeekFlag

type EvtSeekFlag uint32

EvtSeekFlag defines the relative position in the result set from which to seek.

const (
	// EvtSeekRelativeToFirst seeks to the specified offset from the first entry
	// in the result set. The offset must be a positive value.
	EvtSeekRelativeToFirst EvtSeekFlag = 1
	// EvtSeekRelativeToLast seeks to the specified offset from the last entry
	// in the result set. The offset must be a negative value.
	EvtSeekRelativeToLast EvtSeekFlag = 2
	// EvtSeekRelativeToCurrent seeks to the specified offset from the current
	// entry in the result set. The offset can be a positive or negative value.
	EvtSeekRelativeToCurrent EvtSeekFlag = 3
	// EvtSeekRelativeToBookmark seek to the specified offset from the
	// bookmarked entry in the result set. The offset can be a positive or
	// negative value.
	EvtSeekRelativeToBookmark EvtSeekFlag = 4
	// EvtSeekOriginMask is a bitmask that you can use to determine which of the
	// following flags is set:
	EvtSeekOriginMask EvtSeekFlag = 7
	// EvtSeekStrict forces the function to fail if the event does not exist.
	EvtSeekStrict EvtSeekFlag = 0x10000
)

type EvtSubscribeFlag

type EvtSubscribeFlag uint32

EvtSubscribeFlag defines the possible values that specify when to start subscribing to events.

const (
	EvtSubscribeToFutureEvents      EvtSubscribeFlag = 1
	EvtSubscribeStartAtOldestRecord EvtSubscribeFlag = 2
	EvtSubscribeStartAfterBookmark  EvtSubscribeFlag = 3
	EvtSubscribeOriginMask          EvtSubscribeFlag = 0x3
	EvtSubscribeTolerateQueryErrors EvtSubscribeFlag = 0x1000
	EvtSubscribeStrict              EvtSubscribeFlag = 0x10000
)

EVT_SUBSCRIBE_FLAGS enumeration https://msdn.microsoft.com/en-us/library/windows/desktop/aa385588(v=vs.85).aspx

type EvtSystemPropertyID

type EvtSystemPropertyID uint32

EvtSystemPropertyID defines the identifiers that identify the system-specific properties of an event.

const (
	// Identifies the Name attribute of the provider element.
	// The variant type for this property is EvtVarTypeString.
	EvtSystemProviderName EvtSystemPropertyID = iota
	// Identifies the Guid attribute of the provider element.
	// The variant type for this property is EvtVarTypeGuid.
	EvtSystemProviderGuid
	// Identifies the EventID element.
	// The variant type for this property is EvtVarTypeUInt16.
	EvtSystemEventID
	// Identifies the Qualifiers attribute of the EventID element.
	// The variant type for this property is EvtVarTypeUInt16.
	EvtSystemQualifiers
	// Identifies the Level element.
	// The variant type for this property is EvtVarTypeUInt8.
	EvtSystemLevel
	// Identifies the Task element.
	// The variant type for this property is EvtVarTypeUInt16.
	EvtSystemTask
	// Identifies the Opcode element.
	// The variant type for this property is EvtVarTypeUInt8.
	EvtSystemOpcode
	// Identifies the Keywords element.
	// The variant type for this property is EvtVarTypeInt64.
	EvtSystemKeywords
	// Identifies the SystemTime attribute of the TimeCreated element.
	// The variant type for this property is EvtVarTypeFileTime.
	EvtSystemTimeCreated
	// Identifies the EventRecordID element.
	// The variant type for this property is EvtVarTypeUInt64.
	EvtSystemEventRecordId
	// Identifies the ActivityID attribute of the Correlation element.
	// The variant type for this property is EvtVarTypeGuid.
	EvtSystemActivityID
	// Identifies the RelatedActivityID attribute of the Correlation element.
	// The variant type for this property is EvtVarTypeGuid.
	EvtSystemRelatedActivityID
	// Identifies the ProcessID attribute of the Execution element.
	// The variant type for this property is EvtVarTypeUInt32.
	EvtSystemProcessID
	// Identifies the ThreadID attribute of the Execution element.
	// The variant type for this property is EvtVarTypeUInt32.
	EvtSystemThreadID
	// Identifies the Channel element.
	// The variant type for this property is EvtVarTypeString.
	EvtSystemChannel
	// Identifies the Computer element.
	// The variant type for this property is EvtVarTypeString.
	EvtSystemComputer
	// Identifies the UserID element.
	// The variant type for this property is EvtVarTypeSid.
	EvtSystemUserID
	// Identifies the Version element.
	// The variant type for this property is EvtVarTypeUInt8.
	EvtSystemVersion
	// This enumeration value marks the end of the enumeration values.
	EvtSystemPropertyIdEND
)

EVT_SYSTEM_PROPERTY_ID enumeration https://msdn.microsoft.com/en-us/library/windows/desktop/aa385606(v=vs.85).aspx

func (EvtSystemPropertyID) String

func (e EvtSystemPropertyID) String() string

type EvtVariantType

type EvtVariantType uint32
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
)

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

type InsufficientBufferError added in v3.8.17

type InsufficientBufferError struct {
	Cause        error
	RequiredSize int
}

func (InsufficientBufferError) Error added in v3.8.17

func (ibe InsufficientBufferError) Error() string

type LogFileInfo

type LogFileInfo struct {
	Attributes      uint32
	LastWrite       time.Time
	Creation        time.Time
	NumberOfRecords uint64
	OldestRecord    uint64
}

func QueryLogFile

func QueryLogFile(hnd EvtHandle) (lfi LogFileInfo, err error)

type Query

type Query struct {
	// Name of the channel or the path to the log file that contains the events
	// to query.
	Log string

	IgnoreOlder time.Duration // Ignore records older than this time period.

	// Whitelist and blacklist of event IDs. The value is a comma-separated
	// list. The accepted values are single event IDs to include (e.g. 4634), a
	// range of event IDs to include (e.g. 4400-4500), and single event IDs to
	// exclude (e.g. -4410).
	EventID string

	// Level or levels to include. The value is a comma-separated list of levels
	// to include. The accepted levels are verbose (5), information (4),
	// warning (3), error (2), and critical (1).
	Level string

	// Providers (sources) to include records from.
	Provider []string
}

Query that identifies the source of the events and one or more selectors or suppressors.

func (Query) Build

func (q Query) Build() (ret string, err error)

Build builds a query from the given parameters. The query is returned as a XML string and can be used with Subscribe function.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL