WindowsEventForwarding.adoc

DSC Resource 'WindowsEventForwarding'

WindowsEventForwarding enables you to configure a server to become an Event Collector role and create complex Subscriptions.

Source	https://github.com/dsccommunity/CommonTasks/tree/main/source/DSCResources/WindowsEventForwarding
DSC Resource	xWindowsEventForwarding
Documentation	xWEFCollector, xWEFSubscription

Note

Creating a subscription can finished with the following warning: The subscription is saved successfully, but it can't be activated at this time. Use retry-subscription command to retry the subscription. If subscription is running, you can also use get-subscriptionruntimestatus command to get extended error status. Error = 0x3ae8. This is a problem with the used wecutil tool in DSC resource xWindowsEventForwarding. In this case open the subscription properties in the EventViewer GUI and press OK. Now the subscription is activated. During Test-DSCConfiguration such a none working subscription could not be identified.

Note	Additional information can be found in the Event Forwarding Guidance.

Table 1. Attributes of category 'WindowsEventForwarding'

Parameter	Attribute	DataType	Description	Allowed Values
NodeType	Mandatory	String	Defines the type of the current node. On a Collector node at least one Subscription must be defined. On a Source node the machine account of the Collector will be added to the local group Event Log Readers. On a Default node only the prequisites can be checked NodeType Source is only supported for CollectorInitiated subscriptions.	Collector Source Default
CheckPrerequisites		Boolean	Checks the prerequistes on the WEF nodes: Built in account Network Service shall be a member of the Event Log Readers group On a domain controller only the membership test of builtin domain user Network Service in domain group Event Log Readers is implemented. Adding builtin users to a domain group with Powershell is not supported.	True False (default)
CollectorName	Mandatory (on Source nodes)	String	Machine account of the Collector node.
FixWsManUrlAcl		Boolean	Fix WsMan communication problem on Windows Server see KB4494462: Events are not forwarded if the collector is running Windows Server Fix is only supported on NodeType Collector	True False
Subscriptions		Hashtable[]	List of complex Subscriptions Subscriptions are only supported on NodeType Collector

Table 2. Attributes of category 'WindowsEventForwarding/Subscriptions'

Parameter	Attribute	DataType	Description	Allowed Values
SubscriptionID	Key	String	Name of the Subscription
SubscriptionType	Mandatory	String	Type of Subscription to create	CollectorInitiated SourceInitiated
Description		String	Description of the Collector subscription
Enabled		String	Sets whether the subscription will be enabled.	True (default) False
Ensure		String	Determines whether to validate or remove the scubscription	Present (default) Absent
DeliveryMode		String	Configures whether the collector will pull events from source nodes or if the source nodes will push events to the collector.	Push (default) Pull
MaxItems		Sint32	The number of events that can occur on the source before they are submitted to the collector.	Default: 1
MaxLatencyTime		Uint64	The maximum amount of time that can pass before events are submitted to the collector.	Default: 20000
HeartBeatInterval		Uint64	Frequency to verify connectivity	Default: 20000
ReadExistingEvents		String	Should the collector read existing or only new events	True False (default)
TransportName		String	Determines whether to require SSL	HTTP (default) HTTPS
TransportPort		String	Set the port number that WinRM should use to make a connection	Default: 5985
ContentFormat		String	Format that event logs will be submitted in	RenderedText (default) Events
Locale		String	Sets the subscription Locale	Default: en-US
LogFile		String	Sets the event log that the collected events will be written to	Default: ForwardedEvents
CredentialsType		String	Sets the credential type used for authenticating to WinRM This attribute is only supported for 'CollectorInitiated' subscriptions. The used DSC resource xWindowsEventForwarding has a bug and requires a patch to support SourceInitiated subscriptions. If you use the unpatched version 1.0.0.0 you get the error message: Failed to save subscription. Error = 0xd. The data is invalid. In file DSCResources\MSFT_xWEFSubscription\MSFT_xWEFSubscription.psm1 move line 171 (<CredentialsType>$CredentialsType</CredentialsType>) before line 177 (<EventSources>) to fix the bug.	Default (default) Basic Negotiate Digest
AllowedSourceNonDomainComputers		String[]	This parameter has not been fully implemented, only required for source initiated scenarios, provide XML to set IssuerCAList, AllowedSubjectList, or DeniedSubjectList if this will be used	Default: empty string
AllowedSourceDomainComputers		String	In Source Initiated scenario this SDDL determines who can push events. Default: O:NSG:NSD:(A;;GA;;;DC)(A;;GA;;;NS) which equates to Domain Computers and Network Service
Query		String[]	Expects an array of hashtables that set which events should be collected, default is all application and system logs
Address		String[]	Expects an array of source node FQDNs. Default source.wef.test to prevent errors when only staging test subscription.

Example of Collector node with CollectorInitiated subscriptions

WindowsEventForwarding:
  NodeType: Collector
  Subscriptions:
    - SubscriptionID: TestSub
      Ensure: Present
      SubscriptionType: CollectorInitiated
      Address:
        - tester.contoso.com
        - tester.contoso.com

Example of Source node with CollectorInitiated subscriptions

WindowsEventForwarding:
  NodeType:      Source
  CollectorName: contoso\collectorserver$

Example of Collector node with SourceInitiated subscriptions

WindowsEventForwarding:
  NodeType: Collector
  FixWsManUrlAcl: true
  Subscriptions:
    - SubscriptionID: Domain Computer Events
      Ensure: Present
      Description: Important security events from domain computers
      SubscriptionType: SourceInitiated
      AllowedSourceDomainComputers: 'O:NSG:BAD:P(A;;GA;;;DC)(A;;GA;;;DD)S:'  # Domain Computers & Domain Controllers
      Query:
        - 'Security:*[System[(Level=1  or Level=2 or Level=3)]]'

Example of Source node with SourceInitiated subscriptions

RegistryPolicies:
  Values:
    - Key: "Software\\Policies\\Microsoft\\Windows\\EventLog\\EventForwarding\\SubscriptionManager"
      ValueName: 1
      TargetType: ComputerConfiguration
      ValueData: 'Server=http://collectorserver.contoso.com:5985/wsman/SubscriptionManager/WEC,Refresh=300'
      ValueType: String
      Ensure: Present

    - Key: "Software\\Policies\\Microsoft\\Windows\\EventLog\\Security"
      ValueName: ChannelAccess
      TargetType: ComputerConfiguration
      ValueData: 'O:BAG:SYD:(A;;0xf0005;;;SY)(A;;0x5;;;BA)(A;;0x1;;;S-1-5-32-573)(A;;0x1;;;NS)'
      ValueType: String
      Ensure: Present

    - Key: "System\\CurrentControlSet\\Services\\EventLog\\Security"
      ValueName: CustomSD
      TargetType: ComputerConfiguration
      ValueData: 'O:BAG:SYD:(A;;0xf0005;;;SY)(A;;0x5;;;BA)(A;;0x1;;;S-1-5-32-573)(A;;0x1;;;NS)'
      ValueType: String
      Ensure: Present

Recommended Lookup Options in Datum.yml (Excerpt)

default_lookup_options: MostSpecific

lookup_options:

  WindowsEventForwarding:
    merge_hash: deep
  WindowsEventForwarding\Subscriptions:
    merge_hash_array: UniqueKeyValTuples
    merge_options:
      tuple_keys:
        - SubscriptionID