██╗ ██╗███████╗███████╗ ██████╗ ██╗ ██╗██╗██████╗ █████╗ ███╗ ██╗ ██████╗███████╗
██║ ██║██╔════╝██╔════╝ ██╔════╝ ██║ ██║██║██╔══██╗██╔══██╗████╗ ██║██╔════╝██╔════╝
██║ █╗ ██║█████╗ █████╗ ██║ ███╗██║ ██║██║██║ ██║███████║██╔██╗ ██║██║ █████╗
██║███╗██║██╔══╝ ██╔══╝ ██║ ██║██║ ██║██║██║ ██║██╔══██║██║╚██╗██║██║ ██╔══╝
╚███╔███╔╝███████╗██║ ╚██████╔╝╚██████╔╝██║██████╔╝██║ ██║██║ ╚████║╚██████╗███████╗
╚══╝╚══╝ ╚══════╝╚═╝ ╚═════╝ ╚═════╝ ╚═╝╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝╚══════╝
Windows Event Forwarding (WEF) has proved to be a powerful and reliable log forwarding solution since it was introdused with Microsoft Vista. And, as it is integrated within all modern versions of Microsoft Windows, it becomes an easy choice, when it comes to centralized collection of Windows system and security events. But, as stated in [1] and [2], that choice comes with several limitations, mainly being:
- In large environments you are expected to deploy several collectors with 2,000 to not more than 4,000 clients per each. By default WEF does not provide any builtin solution to balance the load over all collectors, so typically it falls to you to implement such solution yourself.
- Each unique device, connected to any subscription, gets its own registry key to store bookmark and source heartbeat information, as an event source. Those keys are not removed automatically, when the device stops being an active event source, so you are expected to review and remove them yourself to negate potential performance issues in the future.
- All events, received from all event sources, are logged to a single local event log file on the collector's side. No logs segregation solution is available by default for remote events storage. To get such segregation, better performance, retention, sorting, etc. you are given the ability to deploy custom event channels, which you would need to prepare first, using Windows SDK.
From previous section rises the main purpose of this project: to attempt to solve limitations mentioned and provide the community with configurable tools, that require minimal adjustments before being deployed to various environments. The main features of this project are as follows:
- Predefined, ready to deploy custom event channels, allowing for better organising and segregation of event log files.
- Predefined, ready to deploy event subscriptions, divided into several categories for better visibility and analysis.
- Generation of own custom event channels manifest to use with Windows SDK.
- Automatic generation, configuration and deployment of custom event channels and subscriptions.
- Automatic synchronization of domain security groups with domain organizational units.
- Automatic removal of registry keys, belonging to inactive domain event sources.
This repository is organized as follows:
.
├── DSG.json
├── New-WECManifest.ps1
├── New-WECSubscriptions.ps1
├── OptionalScripts.md
├── README.md
├── Remove-StaleWECSubscribers.ps1
├── Set-DSGMembership.ps1
├── Set-WECEventChannels.ps1
├── EventChannelsCollections
│ ├── README.md
│ └── <Event Channels Collection>
│ ├── EventCollectorChannels.csv
│ ├── EventCollectorChannels.dll
│ ├── EventCollectorChannels.man
│ └── README.md
├── EventSubscriptionsCollections
│ ├── README.md
│ └── <Event Subscriptions Collection>
│ ├── [Query] ....xml
│ ├── ...
│ ├── [Query] ....xml
│ ├── EventCollectorSubscriptions.csv
│ └── README.md
└── GroupPolicyObjects
├── README.md
├── Windows Event Collector.md
└── Windows Event Forwarding.md
./GroupPolicyObjects-- some GPO recommendations./EventChannelsCollections/-- collections of predefined custom event channels manifest and DLL files./EventSubscriptionsCollections/-- collections of XML files with xPath queries for subscriptions./DSG.json-- input data for the./Set-DSGMembership.ps1script./New-WECManifest.ps1-- main script for generation of custom event channels manifest file./Set-WECEventChannels.ps1-- main script for generation, configuration and deployment of custom event channels./New-WECSubscriptions.ps1-- main script for generation, configuration and deployment of custom event subscriptions./Remove-StaleWECSubscribers.ps1-- optional script for automatic removal of registry keys, belonging to inactive domain event sources./Set-DSGMembership.ps1-- optional script for automatic synchronization of managed security groups with current state of associated organizational units
Note: Make sure to thoroughly test all configurations, scripts, subscriptions, etc. in a lab environment before deploying any of them to a production environment.
- Deploy at least minimum required audit and WEF policies to your environment (see Microsoft documentation).
- Make required adjustments to chosen cannels and subscriptions configuration files (see Configuration section below).
- Make sure that required domain security groups for target WEC server(s) to accept as its subscribers exist in domain.
- Deploy custom event channels to the target WEC server(s) (see EventChannelsCollections subdirectory).
- Deploy custom event subscriptions to the target WEC server(s) (see EventSubscriptionsCollections subdirectory).
- (Optional) Deploy scheduled task to run
Remove-StaleWECSubscribers.ps1script to the target WEC server(s) (see Optional Scripts). - (Optional) Deploy scheduled task to run
Set-DSGMembership.ps1script to the target WEC server(s) (see Optional Scripts).
There are 3 types of configuration files, provided with this repository:
- Custom event channels configuration files: Configuration files, that define layout of custom event channels, intended to store events from subscriptions clients. Those files are provided with each custom channels collection within EventChannelsCollections subdirectory and typically have a name:
EventCollectorChannels.csv. You can find out more information about each collection and a layout, that it implements, by looking into that collection's directory. Refer to these instructions, if you want to edit any of them or create your own. - Custom event subscriptions configuration files: Configuration files, that define data, related to configuring and deploying event subscriptions. Those files are provided with each custom subscriptions collection within EventSubscriptionsCollections subdirectory and typically have a name:
EventCollectorSubscriptions.csv. You can find out more information about each collection and subscriptions, that it sets up, by looking into that collection's directory. Refer to these instructions, if you want to edit any of them or create your own. - Security groups and OUs synchronization configuration file: Configuration file, that define which security groups are going to be associated with which organizational units based on which LDAP filter. It works as an input to
Set-DSGMembership.ps1script and nothing else. Only one such configuration file is provided with this repository, beingDSG.json. That file's content is very specific to every environment it can be deployed to. So make sure to put only suitable for your environment data into that file. Also, consider to protect it from unauthorised access, as every time scriptSet-DSGMembership.ps1runs, it uses this configuration file as an input.
Note: Before running any script, make sure that chosen configuration files contain correct up-to-date information.
For more information, see Microsoft documentation [1], [2].
Contributions, fixes, and improvements can be submitted directly against this project as a GitHub issue or pull request. When contributing an update to CustomEventChannels.man, please do not include the compiled .DLL for security reasons. Once your pull request has been merged, we will compile the updated manifest into a DLL and add it to the repository.
Many open source publications were referenced for the development of this project, and we wish to acknowledge those who have contributed to this effort.