Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Important
PREVIEW: The Windows endpoint security platform and the APIs described in this article are in preview. The API surface, supported events, properties, and behavior can change. This article is a conceptual overview, not API reference documentation. Verify declarations and availability for your target Windows build.
The Windows endpoint security platform is a Win32 user-mode framework for security products. It is available in preview starting with the October 2026 (10D) Windows 11 client releases: version 25H2 (OS build 26200.9818) and version 26H2 (OS build 26300.9818). The platform uses a shared OS-provided driver to observe system activity and deliver events to user-mode clients. Clients define rules to observe or affect supported events without each product implementing its own kernel-mode monitoring driver.
This article describes the event model, client lifecycle, property and context APIs, filters, collections, rules, and event queues. Use the headers and materials provided for your Windows build to verify exact declarations and availability.
Register and connect a client
A WESP product is a program or service that uses the platform. A product can register one or more client IDs. Registration persists across connections; each client ID can have only one active connection at a time. Each connection is represented by an opaque ESP_CLIENT handle, which the product passes to APIs that require a connected client.
The client library is espclient.dll; the platform driver is wesp.sys.
| API | Purpose |
|---|---|
EspRegisterClient |
Registers a client descriptor. The client ID and altitude must be unique. |
EspUnregisterClient |
Removes a registration and its persisted client state. Disconnect the client first. |
EspConnectClient |
Connects a registered client and returns an ESP_CLIENT handle. |
EspDisconnectClient |
Disconnects the handle and releases client-associated memory. Process termination also disconnects the client. |
EspQueryClientDescriptor |
Retrieves a descriptor for a registered or connected client. The returned allocation is released with EspFreeMemory. |
EspEnumerateRegisteredClients |
Lists registered client IDs. Free the returned array with EspFreeMemory. |
EspEnumerateConnectedClients |
Lists connected client IDs. Free the returned array with EspFreeMemory. |
EspGetEventCapabilities |
Reports the current client's supported capabilities for an event type. |
EspRegisterClient and EspUnregisterClient are installation and uninstallation operations, respectively. Don't register a client each time its service starts. A product can use multiple client IDs, but each ID supports only one active connection at a time. Close the active connection with EspDisconnectClient when the service no longer needs it.
EspFreeMemory releases buffers allocated by WESP APIs. EspInitUnicodeString initializes an ESP_UNICODE_STRING from a null-terminated string, and ESP_CONSTANT_UNICODE_STRING initializes one from a constant string.
Registration fails if the client ID or altitude is already registered.
Event capabilities
Call EspGetEventCapabilities to obtain the supported capabilities for a specific event and client. Some event types aren't supported on earlier Windows releases, and some events don't support every capability, such as blocking or allowing an operation.
A client's capabilities depend on its enhanced key usage (EKU) being present in the appropriate WESP Code Integrity policy. Future platform updates will provide distinct subsets of capabilities to different client types.
Events
WESP represents monitored system activity with ESP_EVENT_TYPE values. The preview specification describes these event categories:
| Category | Event types |
|---|---|
| Thread | ESP_EVENT_TYPE_THREAD_CREATE, ESP_EVENT_TYPE_THREAD_START, ESP_EVENT_TYPE_THREAD_TERMINATE |
| Process | ESP_EVENT_TYPE_PROCESS_CREATE, ESP_EVENT_TYPE_PROCESS_TERMINATE, ESP_EVENT_TYPE_PROCESS_LOAD_IMAGE |
| File object | ESP_EVENT_TYPE_FO_CREATE, ESP_EVENT_TYPE_FO_OPEN, ESP_EVENT_TYPE_FO_READ, ESP_EVENT_TYPE_FO_WRITE, ESP_EVENT_TYPE_FO_CLEANUP |
| File system | ESP_EVENT_TYPE_FS_CREATE_FILE_SECTION, ESP_EVENT_TYPE_FS_QUERY_FILE_INFORMATION, ESP_EVENT_TYPE_FS_SET_FILE_INFORMATION, ESP_EVENT_TYPE_FS_SET_FILE_SECURITY, ESP_EVENT_TYPE_FS_QUERY_DIRECTORY_INFORMATION, ESP_EVENT_TYPE_FS_FSCTL_FILE, ESP_EVENT_TYPE_FS_SET_EA, ESP_EVENT_TYPE_FS_QUERY_OPEN_FILE, ESP_EVENT_TYPE_FS_LOCK_FILE, ESP_EVENT_TYPE_FS_UNLOCK_FILE |
| KTM transaction | ESP_EVENT_TYPE_KTM_TRANSACTION_COMMIT, ESP_EVENT_TYPE_KTM_TRANSACTION_ROLLBACK |
| Volume | ESP_EVENT_TYPE_VOLUME_MOUNT, ESP_EVENT_TYPE_VOLUME_DISMOUNT, ESP_EVENT_TYPE_VOLUME_FSCTL |
| Named pipe | ESP_EVENT_TYPE_PIPE_CREATE |
| Mailslot | ESP_EVENT_TYPE_MAILSLOT_CREATE |
| Registry | ESP_EVENT_TYPE_REG_CREATE_KEY, ESP_EVENT_TYPE_REG_OPEN_KEY, ESP_EVENT_TYPE_REG_DELETE_KEY, ESP_EVENT_TYPE_REG_SET_VALUE_KEY, ESP_EVENT_TYPE_REG_DELETE_VALUE_KEY, ESP_EVENT_TYPE_REG_RENAME_KEY, ESP_EVENT_TYPE_REG_REPLACE_KEY, ESP_EVENT_TYPE_REG_RESTORE_KEY, ESP_EVENT_TYPE_REG_SET_KEY_SECURITY, ESP_EVENT_TYPE_REG_QUERY_KEY, ESP_EVENT_TYPE_REG_QUERY_VALUE_KEY, ESP_EVENT_TYPE_REG_SAVE_KEY, ESP_EVENT_TYPE_REG_LOAD_KEY, ESP_EVENT_TYPE_REG_ENUM_KEY, ESP_EVENT_TYPE_REG_ENUM_VALUE_KEY |
| Object manager | ESP_EVENT_TYPE_OB_CREATE_HANDLE, ESP_EVENT_TYPE_OB_DUPLICATE_HANDLE |
| Boot | ESP_EVENT_TYPE_BOOT_LOAD_DRIVER |
Not every event supports every rule action or completion notification. Check event capabilities and the event-specific configuration before depending on a behavior.
Event objects, properties, and references
An event can refer to several WESP event objects, such as the current process and thread, a target file, or a registry key. ESP_EVENT_OBJECT is an opaque handle to one such object. The platform supports these object types:
| Object | Represents |
|---|---|
| Thread and process | A thread or process instance. |
| File stream and file | A physical stream on a volume, or a persistent on-disk file that exists independently of open handles. |
| File object | A single open instance. Multiple file objects can refer to the same file, and a file object can target a file stream, volume, pipe, or mailslot. |
| Volume and disk | A physical volume or disk. |
| Registry key and registry key object | A persistent key, or an open handle to a key. |
| Desktop, KTM transaction, pipe, and mailslot | The corresponding system object or instance. |
| Token | A token instance. |
Call EspGetEventObjectId to retrieve an object's ID and EspGetEventObjectType to retrieve its type. An event object's ID is unique during a boot session, remains constant for that WESP event object's lifetime, and is consistent across clients.
Understand event object lifetimes
An ESP_EVENT_OBJECT received in a notification is a non-owning handle. WESP keeps the event objects and their IDs valid until the client completes that notification with EspCompleteEventNotification. The underlying kernel object or entity might no longer exist by the time an asynchronous notification is processed, so a later property query can fail.
WESP can destroy and recreate an event object while its underlying entity remains alive. The recreated object isn't guaranteed to have the same ID. A strong reference acquired with EspCreateEventObjectReference keeps the event object and its context alive, but doesn't keep the underlying kernel object alive. Setting a context key also retains the event object while its backing entity exists; WESP releases that implicit reference when the entity is destroyed. These references let clients stabilize object identity across events without extending the backing entity's lifetime.
Query properties
Property-query APIs return an array of ESP_PROPERTY values in the order of the requested property IDs. Use the matching EspGetProperty* helper to extract a typed value. A property can instead contain an error when the driver couldn't retrieve it, for example if its backing object no longer exists. Release returned allocations with EspFreeMemory.
| Object or scope | Query API | Support check |
|---|---|---|
| Client | EspQueryClientProperties |
EspIsClientPropertySupported |
| Event | Properties can be requested in event rule configuration. | EspIsEventPropertySupported |
| Thread | EspQueryThreadProperties |
EspIsThreadPropertySupported |
| Process | EspQueryProcessProperties |
EspIsProcessPropertySupported |
| File stream | EspQueryFileStreamProperties |
EspIsFileStreamPropertySupported |
| File | EspQueryFileProperties |
EspIsFilePropertySupported |
| File object | EspQueryFileObjectProperties |
EspIsFileObjectPropertySupported |
| Volume | EspQueryVolumeProperties |
EspIsVolumePropertySupported |
| Disk | EspQueryDiskProperties |
EspIsDiskPropertySupported |
| Registry key | EspQueryRegistryKeyProperties |
EspIsRegistryKeyPropertySupported |
| Registry key object | EspQueryRegistryKeyObjectProperties |
EspIsRegistryKeyObjectPropertySupported |
| Desktop | EspQueryDesktopProperties |
EspIsDesktopPropertySupported |
| KTM transaction | EspQueryKtmTransactionProperties |
EspIsKtmTransactionPropertySupported |
| Pipe | EspQueryPipeProperties |
EspIsPipePropertySupported |
| Mailslot | EspQueryMailslotProperties |
EspIsMailslotPropertySupported |
| Token | EspQueryTokenProperties |
EspIsTokenPropertySupported |
The EspGetProperty* helper family includes EspGetPropertyError, EspGetPropertyContextKeyInfo, EspGetPropertyBool, EspGetPropertyUint8, EspGetPropertyUint16, EspGetPropertyUint32, EspGetPropertyUint64, EspGetPropertyInt32, EspGetPropertyUnicodeString, EspGetPropertyNtStatus, EspGetPropertyFileTime, EspGetPropertyMemoryAddressBasic, EspGetPropertyFileId128, EspGetPropertyUsn, EspGetPropertySigningLevel, EspGetPropertyEaList, EspGetPropertySecurityDescriptor, EspGetPropertyBuffer, EspGetPropertyStringList, EspGetPropertyGuid, EspGetPropertyAcl, EspGetPropertySid, EspGetPropertyImpersonationLevel, EspGetPropertyTokenPrivileges, EspGetPropertyTokenGroups, EspGetPropertyTokenType, EspGetPropertyTokenElevationType, EspGetPropertyTransactionOutcome, EspGetPropertyTransactionState, EspGetPropertyStorageBusType, EspGetPropertyDeviceType, EspGetPropertySubsystemInformationType, and EspGetPropertyFoTargetObjectType. Each helper checks the property's variant type and returns an error if it doesn't match.
When a notification must contain data that might no longer be queryable later, request the property in the rule configuration. WESP captures configured properties at event time and includes them with the notification. A property can report an HRESULT error if the driver couldn't retrieve its value.
Retain event objects
WESP provides general reference APIs and typed creation APIs:
| API group | APIs |
|---|---|
| General references | EspCreateEventObjectReference, EspCreateEventObjectReferenceById, EspDuplicateEventObjectReference, EspCloseEventObjectReference, EspGetEventObjectFromReference |
| Thread and process | EspCreateThreadReference, EspCreateProcessReference |
| File stream and file | EspCreateFileStreamReferenceById, EspCreateFileStreamReferenceByPath, EspCreateFileReferenceById, EspCreateFileReferenceByPath |
| Other objects | EspCreateVolumeReference, EspCreateDiskReference, EspCreateRegistryKeyReference, EspCreateDesktopReference, EspCreatePipeReference, EspCreateMailslotReference, EspCreateThreadTokenReference, EspCreateProcessTokenReference |
Use an explicit reference when you need to query an event object or update its context after completing the notification that supplied it. A strong reference keeps the WESP event object and its context alive, but doesn't keep the underlying kernel object or entity alive. WESP closes explicit references when the client disconnects or its process terminates; call EspCloseEventObjectReference when a reference is no longer needed.
Context keys
Context keys let a client associate client-private state with an event object, an event, or the client itself. A key is a UINT32 with at most 31 bits; its value is an integer, Unicode string, or buffer. Each client has an independent context-key namespace.
| API | Purpose |
|---|---|
EspSetEventObjectContextKey |
Adds, changes, or removes a key on an event object. |
EspEnumerateAllEventObjectContextKeys |
Lists keys on an event object. Free the returned array with EspFreeMemory. |
EspSetClientContextKey |
Adds, changes, or removes a key on a client. |
EspEnumerateAllClientContextKeys |
Lists keys on a client. Free the returned array with EspFreeMemory. |
The ESP_*_PROPERTY_ID_CONTEXT_KEY(key) macros expose context keys through the typed property system. WESP defines macros for event, client, thread, process, file stream, file, file object, volume, disk, registry key, registry key object, desktop, KTM transaction, pipe, mailslot, and token properties. The macro sets the high bit in the property ID; keep the supplied key within the 31-bit range.
Rules can update context keys automatically, cache properties or event parameters in a key, and use key values in filters. Context updates are atomic for an individual client, event, or event object, but a group of updates targeting different objects isn't guaranteed to be atomic as a whole.
Setting a context key on an event object implicitly keeps that event object alive while its backing kernel object or entity exists. When the backing object is destroyed, WESP releases this reference, so context keys don't keep event objects alive indefinitely.
Filters and collections
Filters test event, client, or event-object values. Typed filter APIs use property IDs for the corresponding object type; EspCreateFilter creates a non-typed filter for event parameters that don't have a property ID.
| Filter scope | Creation API |
|---|---|
| Non-typed comparison | EspCreateFilter |
| Event and client | EspCreateEventFilter, EspCreateClientFilter |
| Thread and process | EspCreateThreadFilter, EspCreateProcessFilter |
| File stream, file, and file object | EspCreateFileStreamFilter, EspCreateFileFilter, EspCreateFileObjectFilter |
| Volume and disk | EspCreateVolumeFilter, EspCreateDiskFilter |
| Registry key and registry key object | EspCreateRegistryKeyFilter, EspCreateRegistryKeyObjectFilter |
| Desktop and KTM transaction | EspCreateDesktopFilter, EspCreateKtmTransactionFilter |
| Pipe, mailslot, and token | EspCreatePipeFilter, EspCreateMailslotFilter, EspCreateTokenFilter |
Use EspCreateAndFilter, EspCreateOrFilter, EspCreateXorFilter, and EspCreateNotFilter to compose filters. EspCloseFilter releases a filter reference. Typed filters can only be combined with filters for the same object type. Non-typed filters can only be combined with non-typed filters that use the same comparison type.
The comparison structures support integer, Boolean, string, binary, context-key, and other WESP-defined comparison types. A comparison can use a raw value, a binding key, or a collection where supported. If WESP can't evaluate a filter or the data doesn't apply to that event, the filter doesn't match.
EspStringMatchesPattern accepts ESP_UNICODE_STRING values for a string and pattern and returns whether they match.
Collections provide reusable sets of integer, string, or variable-size binary values for filters. They are private to a client and are reference-counted. A persisted rule can reference only persisted collections; WESP deletes a persisted collection when no rules reference it.
| API | Purpose |
|---|---|
EspCreateCollection, EspOpenCollection |
Create a collection or open one by ID. |
EspCloseCollection |
Release a collection reference. |
EspGetCollectionId, EspGetCollectionType |
Retrieve collection identity and type. |
EspUpdateCollection |
Add or remove entries in an atomic update; affected filters see the update immediately. |
EspEnumerateCollectionEntries |
Retrieve collection entries; free the returned allocation with EspFreeMemory. |
EspEnumerateCollectionIds |
Enumerate a client's collection IDs for a specified lifetime. |
Rules and rule configuration
A rule describes an event type, filters, configuration, lifetime, and action. EspCreateRule creates a rule object but doesn't activate it. Call EspUpdateRules to add it to a client.
| API | Purpose |
|---|---|
EspCreateRule, EspCloseRule, EspGetRuleId |
Create, release, and retrieve the ID of a rule. Closing a local rule reference doesn't remove the rule from WESP. |
EspUpdateRules |
Atomically add, add or replace, enable, disable, or remove rules in the supplied order. |
EspRemoveAllRulesForClient |
Remove all rules for a client. |
EspRemoveRulesForClient |
Remove rules with a specified lifetime. |
EspEnumerateAllRulesForClient, EspEnumerateRuleIds |
Enumerate rule IDs; free returned arrays with EspFreeMemory. |
Rule lifetimes have different retention and startup behavior:
| Lifetime | Behavior and limits |
|---|---|
ESP_RULE_LIFETIME_CLIENT_SESSION |
The rule is removed when the client disconnects. |
ESP_RULE_LIFETIME_BOOT_SESSION |
The rule remains for the current boot session and is deleted when the computer restarts. |
ESP_RULE_LIFETIME_PERSISTED |
The rule persists across restarts and continues to apply while the client is disconnected. It can only use a persisted event queue. |
ESP_RULE_LIFETIME_PERSISTED_EARLY_BOOT |
The rule persists across restarts and is also applied during the Early Launch Anti-Malware (ELAM) phase of early boot. This lifetime is limited to registry events and boot-driver-load events, can't reference filesystem-related objects in its configuration, and requires a persisted event queue. The rule continues to apply after the ELAM phase. |
The rule actions define how WESP handles a match:
| Action | Behavior |
|---|---|
ESP_RULE_ACTION_NOTIFY |
Sends an asynchronous notification when the rule matches. |
ESP_RULE_ACTION_NOTIFY_ON_COMPLETION |
Sends a notification when a supported event completes. A matching pre-operation rule must opt in with ESP_RULE_FLAGS_NOTIFY_ON_COMPLETION; not every event supports this action. |
ESP_RULE_ACTION_NO_NOTIFY |
Updates context keys or modifies event data without notifying the client, then ends rule evaluation for the client. |
ESP_RULE_ACTION_IGNORE |
Ignores the event to stop rule processing early, for example for events originating from the client's own process. |
ESP_RULE_ACTION_BLOCK |
Blocks the event, if the client has the capability and the event supports blocking. A block ends evaluation for that event. |
ESP_RULE_ACTION_ALLOW |
Explicitly allows an event for a limited set of event types; another client can still block it. |
ESP_RULE_ACTION_MATCH_SUBRULES |
Evaluates the rule's subrules after the parent rule matches. |
ESP_RULE_ACTION_CONTINUE_MATCHING_NEXT_RULE |
Continues to the next top-level rule for the client. |
ESP_RULE_ACTION_CONTINUE_MATCHING_NEXT_SUBRULE |
Continues to the next subrule; this action is valid only on a subrule. |
Rule evaluation proceeds by client altitude, with higher altitudes evaluated first. Within a client, top-level rules are evaluated by ascending OrderGroup; WESP doesn't guarantee order within one group. A matching rule normally ends evaluation for that client. Continue actions advance to another rule or subrule, and MATCH_SUBRULES evaluates the matching rule's subrules. A block ends evaluation for the event. Rules generally run before an operation. NOTIFY_ON_COMPLETION rules run after it, and an event can therefore produce both pre-operation and completion notifications when configured.
Each event type has an ESP_*_CONFIG structure that configures its event parameters and related event objects. Rule configuration can:
- Apply event, client, and nested object filters.
- Request event, client, or object properties to capture into notifications.
- Update event, client, or object context keys.
- Bind values from event parameters, properties, or context keys for comparisons elsewhere in the rule.
- Specify subrules and, for supported events, event modifications.
Binding keys are numeric identifiers scoped to a rule. A key resolves to an integer, string, or binary value during evaluation, allowing a filter to compare fields from different objects or event parameters.
Event modification is configured through ESP_EVENT_MODIFY and an event-specific modification structure. It can change supported event data before WESP builds a notification. Use only modifications supported for the event type and available to the client; don't assume that every observed operation can be modified.
Event queues and notifications
An event queue receives notifications from rules that reference it. A client can connect a queue with a callback or an I/O completion port (IOCP). Callbacks can execute concurrently when the queue uses multiple worker threads. Use one worker thread when your callback processing requires serialization. Notifications have event IDs that help identify event order.
| API | Purpose |
|---|---|
EspCreateEventQueue, EspOpenEventQueue, EspCloseEventQueue |
Create, open, or release an event queue. |
EspGetEventQueueId |
Retrieve the queue ID. |
EspConnectEventQueueWithCallback |
Connect a queue using a callback. Multiple worker threads can invoke the callback concurrently; set the worker count to one when processing must be serialized. |
EspConnectEventQueueWithIocp |
Connect a queue to an IOCP and return its handle. Close the returned handle with CloseHandle. |
EspDisconnectEventQueue |
Disconnect a queue. Rules continue to be evaluated, and notifications are buffered until reconnection. |
EspClearEventQueue |
Clear notifications that haven't been dequeued. |
EspEnumerateEventQueueIds |
Enumerate queue IDs for a client and lifetime. |
EspSetEventQueueStateChangeCallback |
Receive notifications when queue memory usage crosses configured thresholds. |
EspRemoveEventQueueStateChangeCallback |
Remove a queue's state-change callback. |
EspAllocateEventNotification, EspArmEventNotification |
Allocate a notification object and arm it to receive events. |
EspCompleteEventNotification |
Complete a received notification. Its fields and structures are invalid after completion. |
EspFreeEventNotification |
Free an allocated notification after no queue is using it. |
An event queue remains alive while it has references, including references held by rules. Its MaxCapacityBytes setting limits memory used to buffer notifications; when the queue reaches its maximum capacity, WESP drops new notifications. A state-change callback can report that the queue is full, that a configured memory threshold was exceeded, or that usage recovered to its recovery threshold. Remove the callback with EspRemoveEventQueueStateChangeCallback when it is no longer needed.
Notifications are queued in event order, but multiple worker threads can cause callbacks or IOCP messages to be processed out of order. Use one worker thread when processing order must be preserved. Call EspCompleteEventNotification only after the client has finished using the notification's data; completion invalidates its fields and structures. Re-arm the notification to receive another event. Don't free an armed notification. Disconnect the queue before freeing its notification objects.
For persisted rules, notifications can be buffered while the client is disconnected. On connection, enumerate and reconnect the persisted event queue using the same queue ID. Check ESP_EVENT_NOTIFICATION_FLAGS_DISCONNECTED to identify notifications from activity while the client was disconnected.