Windows Event Collector (WEC)

Synopsis

Creates a Windows Event Collector (WEC) server that accepts event forwarding connections from Windows clients using the WS-Management (WS-Man) protocol. Supports Kerberos/SPNEGO and TLS mutual authentication, subscription-based event filtering, bookmark persistence for resumable collection, SLDC/LZNT1 decompression, and multiple workers for high-throughput scenarios.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: wec
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    port: <numeric>
    protocol: <string>
    hostname: <string>
    reuse: <boolean>
    workers: <numeric>
    buffer_size: <numeric>
    backpressure_policy: <string>
    max_active_requests: <numeric>
    max_requests_per_socket: <numeric>
    use_x_forwarded_for: <boolean>
    capture_request_headers: <boolean>
    allow_machine_id_mismatch: <boolean>
    ip_allowlist_regex: <string>
    ip_denylist_regex: <string>
    tls:
      status: <boolean>
      cert_name: <string>
      key_name: <string>
      passphrase: <string>
      min_tls_version: <string>
      max_tls_version: <string>
      insecure_skip_verify: <boolean>
    is_auth_required: <boolean>
    client_ca_cert_name: <string>
    kerberos_keytabs:
      - kerberos_keytab: <string>
        kerberos_spn: <string>
    subscriptions:
      - id: <string>
        name: <string>
        channel: <string>
        query: <string>
        content_format: <string>
        read_existing_events: <boolean>
        send_bookmarks: <boolean>
        compress: <boolean>
        targets: <string[]>
        fields:
          - name: <string>
            value: <string>
    batch_size: <numeric>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be wec
tags	N	-	Optional tags
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device

Connection

Field	Required	Default	Description
address	N	"0.0.0.0"	Listen address
port	Y	-	Listen port (typically 5985 for HTTP or 5986 for HTTPS)
protocol	N	"tcp"	Transport protocol.
hostname	N	listen address	FQDN advertised to clients in subscription endpoint URIs

note

If address is 0.0.0.0, set hostname explicitly to a client-resolvable FQDN.

TLS

Field	Required	Default	Description
tls.status	N	false	Enable TLS encryption
tls.cert_name	Y*	cert.pem	TLS certificate
tls.key_name	Y*	key.pem	TLS private key
tls.passphrase	N	-	Passphrase for an encrypted private key
tls.min_tls_version	N	tls1.2	Minimum accepted TLS version (tls1.0, tls1.1, tls1.2, tls1.3)
tls.max_tls_version	N	-	Maximum accepted TLS version. When unset, the highest mutually supported version is negotiated.
tls.insecure_skip_verify	N	false	Skip peer certificate verification. Use only for testing.

* = Required when tls.status is true.

note

tls.min_version is a deprecated alias for tls.min_tls_version, honored only when tls.min_tls_version is unset. Use tls.min_tls_version in new configurations.

Mutual TLS is configured through is_auth_required and client_ca_cert_name, described under Authentication below. This device does not use the tls.client_ca_name and tls.client_auth_required keys read by the other listeners.

note

TLS material fields (cert_name, key_name, ca_name, client_ca_name) accept any of the following:

• File name — resolved relative to the service root directory. Nested paths such as certs/prod/server.pem are supported.
• Absolute path — honored only if it resolves inside the service root. Any path that escapes the root is refused.
• Inline PEM content — used verbatim when the value contains -----BEGIN.
• Environment variable — ${ENV_VAR}.
• Vault reference — $secret{id=...} or $secret{store=...,ref=...}.

note

Port 5986 is the standard WEF/HTTPS port. Plain HTTP on port 5985 is not recommended for production.

Authentication

Field	Required	Default	Description
is_auth_required	N	false	Reject unauthenticated requests
client_ca_cert_name	N	-	CA bundle used to verify client certificates. When unset, the host trust store is used, which is sufficient for domain-joined Windows hosts whose domain CA is already trusted.

Both keys are read at the top level of properties, not under tls.

When is_auth_required is true and no Kerberos keytabs are configured, connecting clients must present a valid certificate and the TLS handshake fails otherwise. When Kerberos keytabs are configured, client certificates are not demanded, because those clients authenticate through SPNEGO in the HTTP Authorization header — requiring a certificate would fail the handshake before Kerberos could negotiate.

Kerberos / SPNEGO

Multiple keytab entries are supported so a single listener can serve clients enrolled in different Kerberos realms.

Field	Required	Default	Description
kerberos_keytabs[].kerberos_keytab	N*		Base64-encoded keytab file content
kerberos_keytabs[].kerberos_spn	N*		Service Principal Name, e.g. HTTP/wec.corp.com

* = Both fields must be provided together per entry. Entries missing either field are skipped with a warning.

note

Keytab data is provided as base64-encoded bytes so no physical keytab file is required on the host. Each entry in kerberos_keytabs is tried in order; the first entry that successfully authenticates the client wins.

Subscriptions

Each subscription defines a set of events that Windows clients will forward to this collector. Clients receive the list of subscriptions during enumeration and begin forwarding matching events automatically.

Field	Required	Default	Description
subscriptions[].id	Y		Unique subscription identifier (used in endpoint URIs)
subscriptions[].name	Y		Human-readable subscription name
subscriptions[].channel	Y		Windows event log channel, e.g. Security, System
subscriptions[].query	Y		XPath filter query or full <QueryList> XML block
subscriptions[].content_format	N	RenderedText	Event content format (RenderedText or Events)
subscriptions[].read_existing_events	N	false	Read events that existed before the subscription was created
subscriptions[].send_bookmarks	N	true	Request bookmark payloads from clients for resumable collection
subscriptions[].compress	N	false	Request SLDC-compressed event batches from clients
subscriptions[].targets	N	-	DNS name patterns restricting which clients receive this subscription (wildcards supported, empty means all clients)

Subscription Fields

Per-subscription fields are injected into every event delivered under that subscription. Values prefixed with __subscription. are resolved from subscription metadata at runtime.

Field	Required	Default	Description
subscriptions[].fields[].name	Y		Field name to inject
subscriptions[].fields[].value	Y		Static value or __subscription.<key> reference

Available __subscription.* references: version, subscriptionName, contentFormat, readExistingEvents, heartbeatInterval, batchTimeout, sendBookmarks, compress, locale.

Advanced Configuration

Performance

Field	Required	Default	Description
reuse	N	true	Enable socket address reuse (SO_REUSEADDR)
workers	N	CPU cores	Number of concurrent event processing workers
buffer_size	N	4096	Async event channel buffer size (number of event batches)
backpressure_policy	N	""	Behavior when the event buffer is full: drop, block, or empty (synchronous fallback)
max_active_requests	N	256	Maximum concurrent in-flight HTTP requests (0 = unlimited)
max_requests_per_socket	N	0	Maximum HTTP requests per TCP connection before close (0 = unlimited)

IP Filtering

Field	Required	Default	Description
ip_allowlist_regex	N		Regex that client IP must match; non-matching IPs receive 403
ip_denylist_regex	N		Regex that client IP must NOT match; matching IPs receive 403

Proxy / Header Handling

Field	Required	Default	Description
use_x_forwarded_for	N	false	Use X-Forwarded-For header to resolve originating client IP
capture_request_headers	N	false	Attach raw HTTP request headers to each event's client identity
allow_machine_id_mismatch	N	false	Allow events when the SOAP MachineID does not match the TLS cert CN (logged as a warning when allowed)

Messages

Field	Required	Default	Description
batch_size	N	10000	Number of log records to read per processing batch

note

queue.interval is a Director service-level setting configured in vmetric.yml and cannot be overridden per device.

Details

How WEF Works

Windows Event Forwarding (WEF) uses the WS-Management protocol over HTTP or HTTPS. When a Windows client connects, it sends an Enumerate request to discover available subscriptions. For each matching subscription it receives, the client begins forwarding events in batches. Each batch may include a bookmark that records the client's position in the event log, allowing the server to resume collection from the correct offset after a restart or subscription version change.

The server handles four main WS-Man actions: Enumerate (returns available subscriptions), Subscribe (client acknowledges a subscription), Events (client delivers a batch of events), and Heartbeat (client signals it is still connected but has no new events to deliver).

Subscriptions and Versioning

When a subscription's configuration changes (channel, query, format, etc.), the server automatically bumps its version identifier and invalidates all stored bookmarks for that subscription. Clients detect the version change during their next heartbeat or event delivery and re-subscribe, causing them to replay events from the beginning of the channel or from the point specified by read_existing_events.

Bookmark Persistence

When send_bookmarks is enabled on a subscription, Windows clients include a BookmarkList XML fragment with each event batch. The server validates and stores this bookmark keyed by client identity and subscription ID. On reconnect or version bump, the stored bookmark is sent back to the client in the SubscribeResponse so it can resume forwarding from where it left off.

Compression

When compress is enabled on a subscription, clients compress event batches using the Streaming Lossless Data Compression (SLDC) algorithm (LZNT1 variant). The server automatically detects and decompresses SLDC payloads. A maximum decompressed size of 64 MB is enforced to prevent memory exhaustion.

Client Identity

The server resolves client identity in order of trust: Kerberos principal (highest), TLS certificate CN (verified chain required), SOAP MachineID / X-Machine-Name header (unverified, used for logging only), and remote IP address (fallback). The MachineName field on a client identity is only populated from verified sources (Kerberos or TLS). ReportedMachineName carries the unverified client-supplied value and should not be used for authorization decisions.

MachineID Mismatch

When TLS client certificates are in use, the server compares the hostname portion of the certificate CN against the SOAP MachineID. A mismatch is rejected by default. Set allow_machine_id_mismatch: true to log the mismatch as a warning and allow the request to proceed. Only the short hostname (before the first .) is compared.

Examples

The following are commonly used configuration types.

Basic

A minimal WEC server listening on the standard HTTP port:

Creating a simple WEC server for a Security event subscription...

devices: - id: 1 name: basic_wec type: wec properties: port: 5985 hostname: wec.corp.com subscriptions: - id: security-events name: Security Events channel: Security query: "*"

TLS with Kerberos Authentication

Securing the collector with TLS and requiring Kerberos authentication:

Production WEC server with TLS and SPNEGO/Kerberos...

devices: - id: 2 name: secure_wec type: wec properties: port: 5986 hostname: wec.corp.com tls: status: true cert_name: wec.crt key_name: wec.key is_auth_required: true kerberos_keytabs: - kerberos_keytab: "${KEYTAB_BASE64}" kerberos_spn: "HTTP/wec.corp.com" subscriptions: - id: security-events name: Security Events channel: Security query: "*" send_bookmarks: true

Multiple Subscriptions with Filtering

Collecting from multiple channels with XPath queries and target restrictions:

Separate subscriptions per channel with event filtering...

devices: - id: 3 name: filtered_wec type: wec properties: port: 5986 hostname: wec.corp.com tls: status: true cert_name: wec.crt key_name: wec.key subscriptions: - id: security-critical name: Critical Security Events channel: Security query: "*[System[(Level=1 or Level=2)]]" content_format: RenderedText send_bookmarks: true targets: - "*.corp.com" - id: system-events name: System Events channel: System query: "*" send_bookmarks: true - id: app-events name: Application Events channel: Application query: "*" targets: - "dc01.corp.com" - "dc02.corp.com"

High-Volume Processing

Performance tuning for large Windows fleets:

Optimizing for high event throughput with multiple workers and compression...

devices: - id: 4 name: performant_wec type: wec properties: port: 5986 hostname: wec.corp.com tls: status: true cert_name: wec.crt key_name: wec.key reuse: true workers: 8 buffer_size: 8192 backpressure_policy: block max_active_requests: 512 batch_size: 5000 subscriptions: - id: all-security name: All Security Events channel: Security query: "*" compress: true send_bookmarks: true

note

The worker count is automatically capped at the number of available CPU cores.

Subscription Fields

Injecting metadata into every event for downstream enrichment:

Tagging events with subscription context for easier routing...

devices: - id: 5 name: enriched_wec type: wec properties: port: 5986 hostname: wec.corp.com tls: status: true cert_name: wec.crt key_name: wec.key subscriptions: - id: dc-security name: DC Security Events channel: Security query: "*" send_bookmarks: true targets: - "*.dc.corp.com" fields: - name: collector_role value: domain_controller - name: subscription_name value: __subscription.subscriptionName - name: content_format value: __subscription.contentFormat

Multi-Realm Kerberos

Serving clients from multiple Kerberos realms with separate keytabs:

Accepting tickets from two different AD domains...

devices: - id: 6 name: multirealm_wec type: wec properties: port: 5986 hostname: wec.corp.com tls: status: true cert_name: wec.crt key_name: wec.key is_auth_required: true kerberos_keytabs: - kerberos_keytab: "${KEYTAB_CORP_BASE64}" kerberos_spn: "HTTP/wec.corp.com" - kerberos_keytab: "${KEYTAB_PARTNER_BASE64}" kerberos_spn: "HTTP/wec.corp.com@PARTNER.COM" subscriptions: - id: all-security name: All Security Events channel: Security query: "*" send_bookmarks: true

warning

Each keytab entry is tried in order. Ensure SPNs are correctly registered in their respective Active Directory domains.

Pipeline Processing

Applying pre-processing pipelines to normalize events before ingestion:

Parsing and normalizing raw Windows event XML...

devices: - id: 7 name: pipeline_wec type: wec pipelines: - windows_event_parser - field_normalizer - timestamp_fixer properties: port: 5986 hostname: wec.corp.com tls: status: true cert_name: wec.crt key_name: wec.key subscriptions: - id: security-events name: Security Events channel: Security query: "*" send_bookmarks: true