Document bounded WMI tree guarantees and record native protection behavior

docs/wmi-descendants.md

@@ -0,0 +1,23 @@
+# Reviewed WMI namespace descendants
+
+`wmi-auditing -WmiIncludeChildren` now inventories existing descendants before an inheritable parent SACL write. It still accepts only the five reviewed local catalog namespaces. The CIMV2 definitions use parent-only flags even when this option is selected; the four reference definitions with flag66 receive the extra safeguards. No descendant is passed to a setter.
+
+```powershell
+./WELA.ps1 wmi-auditing -WmiAction Plan -WmiNamespace 'root\default' -WmiIncludeChildren -ResultsPath tree-plan.json
+./WELA.ps1 wmi-auditing -WmiAction Configure -WmiNamespace 'root\default' -WmiIncludeChildren -DryRun -ResultsPath tree-dry-run.json
+./WELA.ps1 wmi-auditing -WmiAction Configure -WmiNamespace 'root\default' -WmiIncludeChildren -BackupPath C:\Evidence\new-wmi-backup -ResultsPath tree-result.json
+```
+
+Review `Controls[].Descendants` and the full descriptor strings before configuration. Configure builds a fresh in-memory plan, shows the descendant count in its confirmation, and checks that same tree again before writing. The earlier Plan export is documentation of its observation, not a persisted authorization token consumed by Configure. `-Auto` skips the confirmation only; it does not skip the tree checks.
+
+The inventory records every existing child and grandchild within 64 descendants, eight levels and two MiB of descriptor evidence. Two complete passes must agree on names, parent relationships and every full descriptor. Unknown names, duplicates, access failures, caps, incomplete reads and drift fail closed. The scan checks a 30-second budget between namespaces, and native enumeration requests a ten-second timeout. Individual synchronous provider calls cannot be forcibly cancelled, so this is not a hard total runtime limit. Winmgmt must already be running. Host, implementation fingerprints and the full observed caller SID, logon, groups and privilege attributes must remain unchanged.
+
+`before.jsonl` retains the existing parent `DescriptorJson` and `DescriptorMof` fields and adds complete descendant descriptor strings. After confirmation and journaling, another stable inventory must match before the parent-only SACL setter is reached. A journal or guard failure prevents that setter. Original parent ACEs and owner/group/DACL continue to use the existing preservation contract.
+
+After a write, the command requires the same existing descendants, preserves every unrelated descriptor field and original ACE multiplicity, and accepts only the exact requested inherited success ACEs. A returned `SE_SACL_PROTECTED` bit is treated conservatively as a preservation barrier for that namespace and its descendants: the entire observed descriptor must stay unchanged. This does not establish that every WMI provider enforces that bit. Missing inherited entries, an unexpected ACE, changed protection or a new/disappearing namespace is unverified and causes a nonzero result. A final full tree read checks for later drift. Results include the individual descendant observations and diagnostics.
+
+Microsoft documents [namespace inheritance when a child is created](https://learn.microsoft.com/en-us/windows/win32/wmisdk/establishing-inheritance-of-namespace-security) and the [inherited ACE flag](https://learn.microsoft.com/en-us/windows/win32/wmisdk/namespace-ace-flag-constants). This does not establish that adding an inheritable ACE retroactively updates every existing child. A successful parent setter can therefore be followed by a failed descendant verification. The parent addition may remain in place; the command does not retry child writes or claim subtree success. A repeat also fails when the parent is already compliant but existing descendants lack the requested inherited entry. Inspect the recorded native outcomes before choosing a separately reviewed child configuration or recovery procedure.
+
+There is no transaction across the tree. A concurrent change between the final pre-write observations and the provider call remains possible. Namespace names do not establish durable identity across deletion/recreation. No automatic rollback, descendant ACE ownership, future-child behavior, event generation, remote WMI, forwarding or Sigma readiness is inferred. [SetSecurityDescriptor's SACL-only contract](https://learn.microsoft.com/en-us/windows/win32/wmisdk/setsecuritydescriptor-method-in-class---systemsecurity) preserves owner, group and DACL by omitting those fields from the request.
+
+Native acceptance uses generated `root\WelaInheritance_<GUID>` namespaces on disposable Server2022/2025 hosts, runs the production inventory/configuration functions, records exact provider outcomes and removes only owned instances in reverse creation order. It does not redirect the production catalog or write existing production namespaces. Synthetic tests separately exercise caps, stale descriptors, protected subtrees, missing inheritance, unexpected child changes and final failure propagation. Windows11, production target writes, DC/ADCS role behavior and forwarding remain unverified.

docs/wmi-namespace-auditing.md

@@ -29,7 +29,7 @@ The entries come from the [ASD WMI script pinned at 59041b5](https://github.com/
 | `root\subscription` | Everyone | `0x4001E` (262174) | Execute Methods, Full Write, Partial Write, Provider Write, Edit Security | 66 |
 | `root\default` | Everyone | `0x4001F` (262175) | Read plus all preceding rights | 66 |
 
-The numeric subscription mask includes Execute Methods even though the reference script's comment omits it. WELA uses the actual numeric mask. Flags 64 mean success on this namespace; 66 add container inheritance. **By default WELA uses 64 for every selection**, limiting new entries to that namespace. `-WmiIncludeChildren` enables the reference's flag 66 for the four applicable namespaces. This may propagate audit ACEs to inheriting descendants, including existing and future child namespaces; it does not grant access. Child ACL propagation is not enumerated, backed up or verified by this command, and is an explicit additional scope requiring a lab review. Existing inherited entries are retained in either mode. SecurityCenter namespaces are commonly absent on servers; absence is reported rather than treated as successful configuration.
+The numeric subscription mask includes Execute Methods even though the reference script's comment omits it. WELA uses the actual numeric mask. Flags 64 mean success on this namespace; 66 add container inheritance. **By default WELA uses 64 for every selection**, limiting new entries to that namespace. `-WmiIncludeChildren` enables the reference's flag 66 for the four applicable namespaces. This may propagate audit ACEs to inheriting descendants, including existing and future child namespaces; it does not grant access. Existing descendants are now enumerated, journaled and checked before and after the parent-only setter; incomplete inventories or unverified inheritance fail the operation. Review the [bounded descendant safeguards](wmi-descendants.md), including provider limitations and possible parent-only partial outcomes. Existing inherited entries are retained in either mode. SecurityCenter namespaces are commonly absent on servers; absence is reported rather than treated as successful configuration.
 
 ## Privileges, preservation and results
 
@@ -51,9 +51,9 @@ WELA separately observes the effective **Other Object Access Events** audit poli
 
 ## Recovery and remaining lab verification
 
-Keep the new backup directory and result JSON outside temporary folders. `before.jsonl` contains each selected namespace's original `DescriptorJson` and `DescriptorMof`, namespace name and proposed entries. Compare these with a fresh Audit export before making any recovery change. In an elevated WMI Control (`wmimgmt.msc`), select the exact namespace, Security > Advanced > Auditing, and remove only entries that this run added after confirming they were absent from the original descriptor. Restore changed audit flags/masks from the original export if necessary; retain unrelated owner/group/DACL and newer administrative changes. WELA deliberately provides no blind whole-descriptor restore. An existing matching ACE was not created by this run and must not be removed. If descendant inheritance was enabled, inspect affected child namespaces independently and use a pre-change machine snapshot if a complete rollback is needed.
+Keep the new backup directory and result JSON outside temporary folders. `before.jsonl` contains each selected namespace's original `DescriptorJson` and `DescriptorMof`, namespace name and proposed entries. Compare these with a fresh Audit export before making any recovery change. In an elevated WMI Control (`wmimgmt.msc`), select the exact namespace, Security > Advanced > Auditing, and remove only entries that this run added after confirming they were absent from the original descriptor. Restore changed audit flags/masks from the original export if necessary; retain unrelated owner/group/DACL and newer administrative changes. WELA deliberately provides no blind whole-descriptor restore. An existing matching ACE was not created by this run and must not be removed. If descendant inheritance was enabled, retain the descendant snapshots and inspect each reported outcome; these observations confer no descendant ACE ownership or automatic rollback authority. Use a pre-change machine snapshot if a complete rollback is needed.
 
-CI uses synthetic descriptors, a real privileged read of root\cimv2, an in-memory native writer adapter and a read-only dry-run on Windows PowerShell 5.1/7. A separate integration job performs real SACL writes only on uniquely created temporary namespaces on disposable Server 2022/2025 runners, verifies read-back/idempotence and deletes its own namespaces. It never changes the SACL of an existing namespace. **Writes to the five production target namespaces, Windows 11 behavior, benign local/remote event generation, child propagation and forwarding have not been verified by these tests.** Before deployment, use isolated patched snapshots of Windows 11, member server, domain controller and AD CS hosts; record descriptors/effective audit policy before and after, repeat configuration for idempotence, issue benign local and remote calls with known tokens, capture Security 4662 XML, and test the chosen WEF subscription and collector receipt. Validate namespace `ObjectName` and access masks, not EventID alone. These are pending acceptance labs, not claimed Sigma uplift.
+CI uses synthetic descriptors, a real privileged read of root\cimv2, an in-memory native writer adapter and a read-only dry-run on Windows PowerShell 5.1/7. A separate integration job performs real SACL writes only on uniquely created temporary namespaces on disposable Server 2022/2025 runners, verifies read-back/idempotence and deletes its own namespaces. It never changes the SACL of an existing namespace. **Writes to the five production target namespaces, Windows 11 behavior, benign local/remote event generation and forwarding have not been verified by these tests.** A separate [descendant acceptance fixture](wmi-descendants.md) records native existing-child outcomes and owned new-child inheritance without extrapolating production-tree behavior. Before deployment, use isolated patched snapshots of Windows 11, member server, domain controller and AD CS hosts; record descriptors/effective audit policy before and after, repeat configuration for idempotence, issue benign local and remote calls with known tokens, capture Security 4662 XML, and test the chosen WEF subscription and collector receipt. Validate namespace `ObjectName` and access masks, not EventID alone. These are pending acceptance labs, not claimed Sigma uplift.
 
 Additional primary references: [SetSecurityDescriptor and preservation flags](https://learn.microsoft.com/en-us/windows/win32/wmisdk/setsecuritydescriptor-method-in-class---systemsecurity), [namespace access masks](https://learn.microsoft.com/en-us/windows/win32/wmisdk/namespace-access-rights-constants), [namespace inheritance flags](https://learn.microsoft.com/en-us/windows/win32/wmisdk/namespace-ace-flag-constants).