Document actual provider/channel layout and how to customize it (fixes #50)

[ZayanKhan-12]

Background

Fixes #50.

windows-event-channels/README.md states that the manifest "consists of 16 individual providers, each with 7 channels". As @Greyland99 reported, that isn't what CustomEventChannels.man actually contains. A reader expects 112 channels and finds 46, with no explanation for the gap.

Parsing the manifest gives the real layout:

Providers	Channels each
WEC – WEC6	7 (42 total)
WEC7	3
WEC8 – WEC15	0
WEC16	1 (WEC16-Test)

46 channels across 16 providers.

The issue asked for two things: a hint that the empty providers are deliberate headroom, and more detail on how to customize the manifest safely. This PR does both, and fixes two related defects found while verifying the numbers.

Changes

Corrected the inventory — replaced the inaccurate sentence with the real counts, plus a provider table listing each GUID, its channel count and its free slots. The table makes explicit that WEC8–WEC15 are pre-registered headroom, not an oversight: they already have unique GUIDs, so you can add channels without generating GUIDs or restructuring the manifest.

Explained the 7-channel limit — every provider imports the System channel, which consumes one of its 8 slots. The README previously stated the rule without the reason.

Added a "Customizing the manifest" section covering how to add a channel (with a worked XML example), the name/chid/symbol rules, and the pitfalls that aren't obvious:

• provider GUIDs are load-bearing — changing one orphans channels already registered on deployed collectors
• renaming a channel creates a new log and leaves the old .evtx behind
• editing the .man alone changes nothing; the DLL has to be rebuilt and redeployed
• the deployment step sizes all channels at 4 MiB, which is the wrong default for a busy channel like Sysmon

Fixed WEC4-Windows-Update → WEC4-Windows-Updates. The manifest spells it plural. This one is worth calling out: a subscription copied from the README would have pointed at a channel that does not exist, and WEF fails silently here — the subscription shows as active while collecting nothing.

Documented WEC16-Test, which was defined in the manifest but missing from the README list.

Validation script

Added windows-event-channels/validate-event-channels.py, which cross-checks the manifest, the README channel list and every subscription's <LogFile> target, so these can't silently drift apart again.

$ python3 windows-event-channels/validate-event-channels.py
Checked 16 providers and 46 channels.

1 warning(s):

  - channel 'WEC3-External-Devices' has symbol 'WEC3_External_devices'; expected 'WEC3_External_Devices' (casing only)
OK: manifest, README and subscriptions are consistent.

It catches malformed XML, providers over the 7-channel limit, duplicate names/chids/symbols, hyphens in symbols, README/manifest drift, and subscriptions targeting undefined channels. Standard library only, read-only, no network or subprocess calls, and it runs on macOS and Linux as well as Windows. Exits non-zero on failure.

I verified it against ten injected faults (missing channel, 8th channel on a full provider, hyphen in a symbol, disabled channel, duplicate name, README drift in both directions, wrong table count, malformed manifest and malformed subscription); each is caught with a specific message, and the unmodified tree passes.

The one warning is pre-existing: WEC3-External-Devices uses the symbol WEC3_External_devices. Symbols are compile-time C# identifiers and the channel name is what gets registered, so this is cosmetic — I deliberately left the manifest untouched rather than desync it from the checked-in DLL, and made the check a non-fatal warning.

Notes for reviewers

• No changes to CustomEventChannels.man, CustomEventChannels.dll or any subscription. Documentation and a new script only.
• The two commits are independent — the second adds a CLAUDE.md with repository guidance for AI coding assistants. Happy to drop it if it's not something you want in the repo; the first commit stands alone and is what closes Event Providers and Channels - DB Audit Events #50.
• I could not test the Windows-side workflow (compiling the manifest, importing subscriptions) from macOS. The manifest parsing, the documented counts and GUIDs, and the cross-checks are all verified programmatically against the files in the repo.

[palantirtech]

Thanks for your interest in palantir/windows-event-forwarding, @ZayanKhan-12! Before we can accept your pull request, you need to sign our contributor license agreement - just visit https://cla.palantir.com/ and follow the instructions. Once you sign, I'll automatically update this pull request.