Add reviewable GPO audit-policy deployment packages (#415)

* Add reviewable GPO audit-policy deployment components

* Link GPO audit package changelog to PR 415

* Check GPO verification exit code from a real CLI process

docs/gpo-audit-packages.md

@@ -0,0 +1,60 @@
+# GPO audit-policy deployment packages
+
+`gpo-package` builds reviewable **offline components** from WELA's shared advanced audit-policy profiles. It does not generate a GPO backup, create/import a domain GPO, configure local policy or run LGPO. `Plan` is the default. The target role/build is explicitly declared by the operator; the exporter never assumes the machine running WELA is the deployment target.
+
+```powershell
+./WELA.ps1 gpo-package -GpoProfile wela-2.2.0 -Role Client -Build 26100
+./WELA.ps1 gpo-package -GpoAction Export -GpoProfile wela-2.2.0 `
+  -Role Client -Build 26100 -GpoOutputPath .\audit-components -DryRun
+./WELA.ps1 gpo-package -GpoAction Export -GpoProfile wela-2.2.0 `
+  -Role Client -Build 26100 -GpoOutputPath .\audit-components
+./WELA.ps1 gpo-package -GpoAction Verify -GpoOutputPath .\audit-components
+
+# A source minimum may need an explicit expansion to fit exact GPO semantics.
+./WELA.ps1 gpo-package -GpoAction Export `
+  -GpoProfile microsoft-wef-reviewed-2026-09 -Role MemberServer -Build 20348 `
+  -GpoMinimumMode PromoteToBoth -GpoOutputPath .\wef-audit-components
+```
+
+Plan/Export require `-GpoProfile`, `-Role` and `-Build`, validated against the bundled profile's applicability. `-IncludeOptional` includes optional entries. Verify takes only its existing package path and reads context from the manifest; no context overrides are accepted. Use the returned PowerShell object's `Plan.Controls`/`Plan.Blockers` to inspect a plan. Export includes JSON and Markdown, so `-ResultsPath` and unrelated configuration/backup/profile options are rejected. `-DryRun` is supported only for Export and creates no files or directories. GPO-only parameters are rejected before unrelated profile command dispatch.
+
+## Components and semantics
+
+| File | Content |
+| --- | --- |
+| `audit.csv` | UTF-8 without BOM, CRLF, documented seven-column header; System subcategory GUIDs with exact positive values 1/2/3 only |
+| `GptTmpl.inf` | UTF-16LE with BOM; only `SCENoApplyLegacyAuditPolicy=1` as a DWORD security-template registry value |
+| `manifest.json` | Profile/version/hash, declared role/build, source provenance, all control dispositions, hashes/lengths/encodings and scope limits |
+| `review.md` | Full control list, exported and omitted settings, minimum expansions, prerequisites and source references |
+| `deployment.md` | Supported genuine-GPO preparation, reviewed create-unlinked procedure, validation and recovery boundaries |
+
+The CSV follows [MS-GPAC message syntax](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-gpac/6494a0f2-8a16-40e2-b87d-328be7d732e0). It contains no per-user exclusions, global object SACLs or audit options. The precedence template follows the mechanism recommended in [MS-GPAC security considerations](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-gpac/e8edc8e2-4b91-433f-b1a2-672d4647e12f). Precedence is a prerequisite, not evidence of the winning domain policy or persistence.
+
+| Shared profile mode | Export treatment |
+| --- | --- |
+| Exact 1, 2, 3 | Same exact mask; may turn off an opposite audit bit on a target |
+| Minimum 1 or 2 | Blocked by default; explicit `PromoteToBoth` emits exact 3 and records each expansion |
+| Minimum 3 | Exact 3, equivalent requirement |
+| Minimum 0 | Omitted; no required bits |
+| Optional | Omitted unless explicitly selected; selected positive mask is exact |
+| Unchanged / Not Configured / Not applicable | Omitted; neither zero nor a delete instruction is emitted |
+| Exact 0 / selected optional 0 | Blocked pending native validation of explicit-disable CSV semantics |
+| Reference-only Windows defaults | Deployment export blocked |
+
+A GPO CSV has no dynamic operation equivalent to WELA's local minimum-mask OR. Promoting a minimum to Both avoids dropping an unknown existing bit but can increase volume. No host snapshot is invented to resolve this. The normative [system-audit value specification](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-gpac/21ad2e80-3011-48ef-be13-cc11ff7bfeb1) distinguishes unchanged 0 from None 4, while Microsoft's [combined example](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-gpac/d77939fe-8fdc-4d06-b08a-13670cc8cbe7) also labels a 0 row No Auditing. This implementation rejects explicit-disable exports instead of choosing unverified behavior. Current non-reference built-in profiles use positive explicit masks; defaults remain documentary only.
+
+## File safety and verification scope
+
+The output's parent directory must exist and the final output directory must be new. Existing files/directories are never reused, and observed symlink/junction components are refused. Export writes an owned sibling staging directory, verifies all expected bytes against the installed profile, then publishes it with a directory rename that refuses a concurrent destination. Verification runs again at the final path. A failure can retain staging/output evidence for review; remove only the owned failed artifact after checking it. No Windows-policy recovery is needed because this workflow changes only package files.
+
+Verify requires exactly the five expected regular files. It checks hashes, lengths and encodings and regenerates the expected policy/review from the installed shared profile schema. Changing a CSV and updating its manifest hash is insufficient: the intended settings and source provenance must still match the installed profile. A profile/generator/guide change can require regeneration and review; retain the WELA version used to create older packages. Hashes provide consistency checks, not a digital signature or trusted origin. Protect both WELA's source and the package and reverify immediately before review/use; concurrent filesystem changes after a check are not prevented.
+
+`ExitCode=0` means the plan has no blockers or component verification succeeded, including a dry-run that produced no package. It does not mean a GPO was created, imported, linked or applied. Reports always retain `ImportableGpoBackup=false`, `DeploymentVerified=false` and `SigmaEvtxCredit=0`.
+
+Only built-in advanced Security audit profiles and the precedence template are supported. Other registry controls, event-log sizing/retention/ACLs, SACLs, AD CS filters, WEF, PowerShell, firewall/SMB/provider settings, privileges and diagnostics are explicitly listed as unsupported. Sysmon is excluded. Follow [the deployment guide](gpo-package-deployment.md) for a genuine GPMC/LGPO preparation path and remaining domain acceptance work. Do not rename this folder or manufacture backup XML to make it look importable.
+
+## Tests and remaining evidence
+
+The offline suite covers shared source/role/build selection, every mode/mask translation, exact-zero/default refusal, optional/role omissions, source fingerprint drift, CSV/template contents, tampering even with updated hashes, fresh-directory collisions, dry-run, filesystem guards and public CLI option boundaries. The Windows workflow targets Server 2022/2025 under PowerShell 5.1 and 7, verifies cross-edition package compatibility, calls native `secedit /validate` on the generated template and checks unchanged effective audit masks/precedence. It does not apply audit CSV or create a domain GPO.
+
+Accepted file syntax and package round-trips do not establish domain import, exact-disable behavior, GPO propagation or event generation. Genuine backup preparation, create-unlinked/import/readback, client/member/DC/AD CS lab application and benign event/collector evidence remain pending. Issue #2 therefore retains deployment acceptance work beyond this package feature.

docs/gpo-package-deployment.md

@@ -0,0 +1,74 @@
+# Preparing and reviewing a genuine audit-policy GPO
+
+This WELA folder contains **deployment components, not a GPO backup**. Do not pass it to `Import-GPO`, copy it into SYSVOL, fabricate `Backup.xml`, or edit a genuine archived backup to insert its files. Microsoft directs administrators to manage archived backups through GPMC. No domain creation, import, linking, filtering, delegation or policy refresh is performed by WELA's package commands. [Microsoft backup/import guidance](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/group-policy/group-policy-backup-restore).
+
+## Prepare the source policy in an isolated domain
+
+1. Verify the component package with the same reviewed WELA version. Read `review.md`, including every omitted/expanded row and object/service prerequisites. Confirm the intended target role, build, scope and source version; these are declared package inputs, not observations of a domain's computers.
+2. On a disposable, snapshotted lab, use GPMC to create a **new unlinked source GPO**. Leave existing GPOs, default domain policies and links untouched. In the Group Policy Management Editor, enter only the exported rows under Computer Configuration > Policies > Windows Settings > Security Settings > Advanced Audit Policy Configuration. `ExportMask` 1 is Success, 2 is Failure, 3 is Success and Failure. Leave omitted rows Not Configured in this new GPO; do not interpret omission as disabling auditing.
+3. In the same GPO, enable Security Options > **Audit: Force audit policy subcategory settings (Windows Vista or later) to override audit policy category settings**. The companion `GptTmpl.inf` shows the exact DWORD requirement. Do not add legacy category audit policy, audit failure options, privileges, SACLs or unrelated registry settings.
+4. Review GPMC's Settings report against the package. Require an exact match for the selected audit GUIDs/masks and precedence=1, with no unexpected Computer or User policy settings. Confirm no links or WMI filter. Review the GPO's security filtering/delegation independently. Back up this source GPO through GPMC or `Backup-GPO` into a fresh protected directory, retaining its **backup-instance ID**, source GPO ID, report and hashes.
+
+This manual source-GPO preparation is the supported path for a narrow, genuine domain backup. Microsoft documents creating an [unlinked GPO](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/group-policy/group-policy-management-console) and generating backups through [Backup-GPO](https://learn.microsoft.com/en-us/powershell/module/grouppolicy/backup-gpo?view=windowsserver2025-ps).
+
+## Optional LGPO lab route
+
+Obtain Microsoft's signed LGPO utility and its documentation from the [Security Compliance Toolkit](https://www.microsoft.com/en-us/download/details.aspx?id=55319); WELA does not bundle or execute it. LGPO v3 documents `/s GptTmpl.inf` for a security template, `/a audit.csv` for advanced auditing and `/b directory /n display-name` for a genuine local-policy backup. These **apply modes change the lab host** and are outside the offline package workflow. Snapshot and record the lab's policy first; inspect all generated settings and compare effective policy before/after. Do not run them on a shared or production administrator workstation.
+
+`/a` and `/ac` differ: `/ac` clears existing advanced auditing before application and copies the CSV into local policy. WELA does not provide a clearing command. `/a` must not be presented as proof of persistent GPO configuration: local policy editor state, effective AuditPol state and the audit client-side extension are separate observations. LGPO `/e audit` enables that extension for local processing, but neither its use nor successful import proves correct later policy application.
+
+LGPO `/b` backs up local policy, including security settings, current advanced audit state, registry policy and configured extensions. **Its output can include settings absent from this package**, even on a lab machine. Review the complete backup in GPMC. If it contains extras, edit a newly created isolated source GPO through GPMC and make a new genuine backup; do not remove files or patch XML inside the archive. A generic local-policy backup is not automatically a narrow WELA audit-only backup. Microsoft explains the difference between [AuditPol state and local policy](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/auditpol-local-security-policy-results-differ).
+
+## Reviewed create-new-unlinked procedure
+
+The following is an **operator procedure for an already prepared, genuine, fully reviewed backup**. It is not generated executable content and WELA does not run it. Review its backup by instance ID through GPMC's Manage Backups/Settings report (or the native `GPMBackupDir.GetBackup` and `GPMBackup.GenerateReport` APIs). A CSV folder is insufficient. Require only the intended computer audit settings and precedence, with no unknown extensions, scripts, preferences, per-user audit entries or unrelated settings.
+
+Use explicit domain and DC parameters for every operation. Check connectivity/authority before creation and do not treat an access error as an absent GPO. Choose a fresh unique name. For example, in an authorized lab using Windows PowerShell and the GroupPolicy module:
+
+```powershell
+# Replace these with the explicitly reviewed lab domain, DC, genuine backup and name.
+$targetDomain = 'lab.example.test'
+$targetDc = 'dc01.lab.example.test'
+$genuineBackupRoot = 'C:\ReviewedGpoBackups'
+$reviewedBackupId = [guid]'11111111-1111-1111-1111-111111111111'
+$newName = 'WELA Audit - reviewed lab candidate'
+$receiptPath = 'C:\Review\new-gpo-receipt.json' # Must not already exist.
+
+if (Test-Path -LiteralPath $receiptPath) { throw 'Use a fresh receipt path.' }
+$existing = @(Get-GPO -All -Domain $targetDomain -Server $targetDc -ErrorAction Stop |
+  Where-Object DisplayName -eq $newName)
+if ($existing.Count) { throw 'The target name already exists; stop without importing.' }
+
+# Do not specify a Starter GPO or pipe to New-GPLink.
+$created = New-GPO -Name $newName -Domain $targetDomain -Server $targetDc -ErrorAction Stop
+[pscustomobject]@{
+  Domain = $targetDomain; Server = $targetDc; GpoGuid = $created.Id
+  Name = $created.DisplayName; BackupId = $reviewedBackupId
+  State = 'Created; import and verification pending'
+} | ConvertTo-Json | Out-File -LiteralPath $receiptPath -Encoding UTF8 -NoClobber -ErrorAction Stop
+
+# Recheck that this exact new GPO is empty and unlinked before importing.
+Get-GPOReport -Guid $created.Id -Domain $targetDomain -Server $targetDc -ReportType Xml
+```
+
+Stop and review the returned GUID, persisted receipt and actual report. Only after confirming that the exact new GPO remains empty and unlinked, execute this separate import step in the same reviewed session:
+
+```powershell
+Import-GPO -BackupId $reviewedBackupId -Path $genuineBackupRoot `
+  -TargetGuid $created.Id -Domain $targetDomain -Server $targetDc -ErrorAction Stop
+Get-GPOReport -Guid $created.Id -Domain $targetDomain -Server $targetDc -ReportType Xml
+```
+
+`New-GPO` creates an unlinked object and refuses a duplicate name. `Import-GPO` imports into the returned **new GUID**, without `-CreateIfNeeded`, name-based targeting or `Restore-GPO`. Importing settings preserves the destination's existing security filtering and links; it does not supply an approved scope of application. Review the actual result, including exact settings and continued absence of links, before considering any later link. Do not assume the backup's security filtering or role metadata protects the new GPO. [New-GPO](https://learn.microsoft.com/en-us/powershell/module/grouppolicy/new-gpo?view=windowsserver2025-ps), [Import-GPO](https://learn.microsoft.com/en-us/powershell/module/grouppolicy/import-gpo?view=windowsserver2025-ps).
+
+If receipt persistence, import or readback fails, stop and retain the created GUID and evidence for manual review. Do not retry against an arbitrary existing GPO or automatically delete an object that another administrator may have changed or linked. This procedure is not a transaction or a lock against concurrent administrators; check the same DC immediately before each operation. Inspect both AD/SYSVOL versions and replication before proceeding beyond the unlinked candidate.
+
+## Deployment acceptance and recovery
+
+After separate approval of scope, stage any linking on an isolated test OU containing only representative disposable clients/servers. Plan role/build targeting and filtering explicitly; WELA's declared Role/Build is documentation, not a generated WMI or security filter. Check precedence, link order, enforcement, inheritance and resultant policy. No deployment link/force-refresh command is included here.
+
+Record the genuine backup, target GUID, actual GPMC settings, RSoP/GPO source evidence, effective audit masks after ordinary policy processing, relevant SACL/service prerequisites, benign generated XML and collector arrival. Unlinked creation/import does not prove any client applied the settings. More specific or enforced policy can change the result. [Group Policy processing](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/group-policy/group-policy-processing).
+
+Rollback must be designed before linking. Preserve existing production GPOs and links throughout preparation. If testing fails, the policy owner should inspect and selectively reverse only the test changes, considering current links, authoritative settings and replication. Unlinking or deleting a GPO is not proof that all effective settings reverted. Retain evidence rather than blindly restoring an old whole-host policy snapshot. No audit-exhaustion test is required or provided.
+
+WELA's automated tests validate package contents and unchanged host settings only. Genuine GPO creation/import, absence of unintended policy settings, AD/SYSVOL replication, client/DC/AD CS application and event/collection evidence remain pending lab acceptance for issue #2. Other WELA controls and Sysmon are outside this package.