repository·master·Indexed 21 days ago
https://github.com/microsoft/krabsetwA C++ library that simplifies interaction with Event Tracing for Windows (ETW), providing mechanisms for enabling traces, registering for event notifications, and parsing event data into strongly typed structures. It includes a .NET wrapper called 'Lobsters' (Microsoft.O365.Security.Native.ETW) and a specialized version for .NET Core (Microsoft.O365.Security.Native.ETW.NetCore). The library supports x64 and ARM64 architectures on Windows 7/Windows 2008R2 and above.
ETWLib is a C# library designed to simplify interactions with Event Tracing for Windows (ETW). It enables developers to:
Microsoft.O365.Security.Native.ETW project designed for multi-targeting both .NET and .NET Core environments using C++/CLI. Unlike the original project, this version includes source files using wildcards, simplifying file management for multi-target builds.A C++ library designed to simplify interacting with Event Tracing for Windows (ETW). It enables managing multiple traces and providers simultaneously and allows client code to register for event notifications. It also includes utilities for parsing generic event data into strongly typed data structures.
A C++ CLI (.NET) wrapper around krabsetw. It exposes the same functionality to .NET applications and is used in production by the Office 365 Security team.
ETWLib uses two primary abstractions to manage event streams:
A Trace represents a stream of events. ETWLib distinguishes between Kernel traces and User traces.
A Provider represents a specific source of ETW events, identified by a unique GUID. Providers use bitflags for event filtering:
Any: If an event meets any of the flags in this property, registered callbacks are triggered.All: If an event meets all the bits in this property, registered callbacks are triggered.Note: The exact semantics of Any and All depend on the specific ETW provider being used; some providers may ignore the All flag if Any is not set.
To receive events, you must:
UserTrace.Provider with its GUID.Any or All bitflags.OnEvent event.trace.Enable(provider).trace.Start().// 1. Create a trace
UserTrace namedTrace = new UserTrace("Muffins McGoo");
// 2. Define a provider with a GUID
Provider powershellProvider = new Provider(Guid.Parse("{A0C1853B-5C40-4B15-8766-3CF1C58F985A}"));
// 3. Set filtering flags and register a callback
powershellProvider.Any = 0x10;
powershellProvider.OnEvent += MyCallbackFunction;
// 4. Enable the provider on the trace
namedTrace.Enable(powershellProvider);
// 5. Start the trace (blocking call)
// Use Task.Run to prevent blocking the main thread
var t = Task.Run(() => namedTrace.Start());
void MyCallbackFunction(EventRecord record)
{
// Handle the event
}Once an event is received, the processing logic follows these steps:
When using krabsetw or Microsoft.O365.Security.Native.ETW, be aware of the following:
start on a trace object is blocking. You may need to manage threads manually to avoid blocking your main application execution.krabsetw package, consult krabs/README.md regarding the TYPEASSERT and NDEBUG compilation flags.Event Tracing for Windows (ETW) is a logging infrastructure used for diagnostics and performance analysis. To use krabsetw effectively, you must understand these key abstractions:
In O365.Security.Native.ETW, event listening is structured around two main abstractions: UserTrace and Provider.
UserTrace: Represents a stream of events. You can create an unnamed trace or a named trace using a string.Provider: Represents a specific source of ETW events, identified by a GUID.To listen to events, you must associate a Provider with a UserTrace using the .Enable(provider) method, and then call .Start() on the trace. Providers use bitflags (Any and All) for event filtering. Note that the exact semantics of these flags depend on the specific ETW provider being used.
// 1. Create a trace
var trace = new UserTrace("MyTraceName");
// 2. Define a provider with a GUID and filtering flags
var provider = new Provider(Guid.Parse("{A0C1853B-5C40-4B15-8766-3CF1C58F985A}"));
provider.Any = 0x01;
provider.All = 0x10;
// 3. Attach an event handler
provider.OnEvent += (record) => { /* handle IEventRecord */ };
// 4. Enable the provider on the trace and start
trace.Enable(provider);
trace.Start();Because starting an ETW trace session requires 'donating' a thread to the ETW subsystem, performance is critical to avoid dropping events:
In Krabs, a user_trace represents a stream of events from ETW-aware applications. You can create an unnamed trace or a named trace by passing a wide-string literal to the constructor.
Note that Krabs distinguishes between user_trace and kernel traces because their APIs differ.
user_trace trace(); // unnamed trace
user_trace namedTrace(L"Muffins McGoo");To begin receiving events, you must follow these steps in order:
trace.enable(provider) for every provider you wish to listen to on that specific trace.trace.start().Important: user_trace::start() is a blocking call. If your application needs to perform other tasks while listening for events, you must call start() on a separate thread.
3. Stop the Trace: Call trace.stop() to cease event collection.
// 1. Enable the provider
namedTrace.enable(powershellProvider);
// 2. Start listening (on a separate thread to avoid blocking the main thread)
void startListening()
{
namedTrace.start();
}
std::thread t(startListening);
// ... do other work ...
// 3. Stop the trace
namedTrace.stop();
t.join();The UserTrace.Start() method is a blocking call that listens for events. To allow your application to perform other tasks while listening for ETW events, you must call Start() on a separate thread, for example using Task.Run().
var t = Task.Run(() => namedTrace.Start());