declarative-ad-framework/CHANGELOG.md

# Changelog

## [2.1.0] - 2026-02-14

AD objects subsystem refactored into modular architecture matching the GPO pattern. New features for password policies, user properties, group protection, and stale object detection.

### AD Objects -- Modular Architecture

Refactored `ADHelper.ps1` from a monolithic library (606 lines) into a loader that dot-sources 6 specialized modules:

- **ADCore.ps1**: CSPRNG password generation (Get-CryptoRandomInt, New-RandomPassword)
- **ADOrganizationalUnit.ps1**: OU ensure/compare
- **ADGroup.ps1**: Security group ensure/compare with accidental-deletion protection
- **ADUser.ps1**: User account ensure/compare with optional property management
- **ADDelegation.ps1**: OU delegation ACLs (schema GUIDs, ACE generation, bitwise subset checking)
- **ADPasswordPolicy.ps1**: Fine-grained password policy (PSO) ensure/compare

### Group Protection

Security groups now get `ProtectedFromAccidentalDeletion = $true` on creation. Existing unprotected groups are remediated on apply. Drift detection in TestOnly mode.

### Extended User Properties

User definitions support optional AD attributes (Description, Title, Department, Mail, etc.) via a `-Properties` hashtable. Core schema keys are explicit parameters; everything else flows through Properties. Works for both new user creation and existing user updates.

### Fine-Grained Password Policies (PSOs)

New `password-policies.ps1` definition file with two admin-tier policies:

- **PSO-MasterAdmins**: 16-char minimum, 30-day max age, 48 history, 3-attempt lockout (precedence 10)
- **PSO-DelegatedAdmins**: 12-char minimum, 42-day max age, 24 history, 5-attempt lockout (precedence 20)

Both override the Default Domain Policy for their linked groups. Property-level drift detection and full AppliesTo group linkage sync.

### Stale Object Detection

New `Get-StaleADObjects.ps1` read-only reporting script. Scans managed OUs for:

- Stale user accounts (no login in N days, default 90)
- Unexpectedly disabled accounts (not intentionally disabled in definitions)
- Empty security groups (zero members)
- Unmanaged users/groups (in managed OUs but not in definition files)
- Pending credential files with age

### Documentation

- Updated FRAMEWORK.md with modular AD architecture, PSO definition format, extended user properties
- Updated CLAUDE.md and README.md with new repo structure and features
- Updated function pairs table and dependency ordering

---

## [2.0.0] - 2026-02-14

Major expansion of the GPO framework. Modular library architecture, 8 new subsystems, and hardening policies deployed across all GPOs.

### GPO Framework -- Modular Architecture

Refactored `GPOHelper.ps1` from a monolithic library into a loader that dot-sources 12 specialized modules:

- **GPOCore.ps1**: SYSVOL paths, version bump, extension GUIDs, DSC helpers
- **GPOPolicy.ps1**: Security policy (GptTmpl.inf), registry settings, restricted groups
- **GPOPermissions.ps1**: GPO links (with order/enforcement), management permissions, security filtering
- **GPOScripts.ps1**: Startup/shutdown/logon/logoff script deployment to SYSVOL
- **GPOAudit.ps1**: Advanced audit policy (53 subcategories in audit.csv)
- **GPOPreferences.ps1**: Group Policy Preferences XML (10 types -- see below)
- **GPOWmiFilter.ps1**: WMI filter creation and GPO linking
- **GPOBackup.ps1**: Pre-apply backup with timestamped snapshots, restore via `Restore-GPOBaseline.ps1`
- **GPOFirewall.ps1**: Windows Firewall rules (`Open-NetGPO` session) and profile management
- **GPOAppLocker.ps1**: AppLocker policy management via `Set-AppLockerPolicy -LDAP`
- **GPOWdac.ps1**: WDAC policy deployment (.xml auto-converted to .p7b via `ConvertFrom-CIPolicy`)
- **GPOFolderRedirection.ps1**: Folder redirection via fdeploy1.ini (12 supported folders)

### GPO Preferences (10 types)

- ScheduledTasks, DriveMaps, EnvironmentVariables, Services (from 1.0)
- **Printers**: Shared printer mapping with default/skip-local options
- **Shortcuts**: Desktop/Start Menu shortcuts (URL, filesystem, shell)
- **Files**: File copy/replace from UNC or local paths
- **NetworkShares**: Local share creation with permissions
- **RegistryItems**: GPP registry items with action modes (distinct from Administrative Templates)
- **LocalUsersAndGroups**: Additive local group membership management (ADD/REMOVE without full replace)
- All types support Item-Level Targeting (ILT) filters

### GPO Operations

- **Restore-GPOBaseline.ps1**: List and restore GPO backups by name and timestamp
- **Get-UnmanagedGPOs.ps1**: Discover orphan GPOs in AD not managed by the framework
- **Automatic backups**: Every apply creates timestamped snapshots (SYSVOL + AD attributes), 5 retained per GPO
- **GPO status management**: `DisableUserConfiguration` / `DisableComputerConfiguration` keys

### New GPO -- Servers-01

- Linked to ExampleServers OU with WMI filter (ProductType = 3)
- Full audit (30 advanced audit subcategories), PowerShell transcription + module logging
- Command-line in process creation events, 256 MB security log
- Firewall: default-deny inbound, allow WinRM/RDP/ICMP/SMB
- GPP LocalUsersAndGroups: MasterAdmins added to Remote Desktop Users

### Hardening Deployed to Existing GPOs

- **Firewall profiles + rules**: Servers-01, AdminWorkstations-01, Workstations-01 (default-deny inbound, allow management traffic)
- **Advanced audit policy**: Servers-01 (30 subcategories), AdminWorkstations-01 (27 subcategories including DPAPI)
- **AppLocker audit mode**: Workstations-01 and AdminWorkstations-01 (Exe/Msi/Script collections, Microsoft-signed + Program Files + Windows + admin unrestricted)
- **WDAC audit mode**: AdminWorkstations-01 (AllowMicrosoft baseline -- all Microsoft root CAs, WHQL drivers, multiple policy format for future supplemental policies)

### Documentation

- **FRAMEWORK.md**: Complete developer reference -- architecture, ensure/compare pattern, all 15 setting types with format documentation, encoding guide, how-to recipes
- Updated README.md with GPO capabilities table, full repo structure, Servers-01
- Updated CLAUDE.md with 12-module library structure

### Bug Fixes

- AppLocker XML element names must match rule type (FilePathRule, FileHashRule, not always FilePublisherRule)
- `Get-NetFirewallRule` uses `-PolicyStore` not `-GPOSession` for reading GPO firewall rules
- `Get-AppLockerPolicy -Domain` is a SwitchParameter (flag), not a string parameter
- XML comments cannot contain `--` (double hyphen) -- .NET XmlSerializer strictly enforces this

---

## [1.0.0] - 2026-02-13

First stable release. Full infrastructure-as-code coverage for the example.internal domain.

### AD Object Management

- **Apply-ADBaseline.ps1**: Idempotent orchestration for OUs, security groups, and user accounts
- **ADHelper.ps1**: Shared functions -- CSPRNG password generation, OU/group/user ensure and compare
- **Credential handoff**: New user passwords saved to ACL-locked files, never printed to console
- **Stale credential warnings**: Files older than 24 hours trigger a warning banner
- **Dependency ordering**: OUs -> groups -> users -> membership sync

### Organizational Units

- ExampleUsers, ExampleWorkstations, ExampleServers, ExampleAdmins, ExampleAdminWorkstations

### Security Groups and Delegation

- **MasterAdmins**: Full Control on all managed OUs, GPO edit rights (self-healing)
- **DelegatedAdmins**: Scoped helpdesk in ExampleUsers (password reset, user properties)
- ACL delegation automated via `delegations.ps1` (Ensure/Compare pattern with AD schema GUIDs)

### Group Policy

- **Apply-GPOBaseline.ps1**: Declarative GPO management -- security policy, registry settings, links, security filtering, management permissions
- **GPOHelper.ps1**: SYSVOL read/write, GptTmpl.inf parsing, GPO versioning, permission management
- **-GpUpdate switch**: Optional `gpupdate /force` after applying
- **-TestOnly mode**: Drift detection across all GPO settings without changes
- **Self-healing permissions**: MasterAdmins edit rights enforced on every run

### GPO Policies

- **Default Domain Policy**: Password (7-char min, 42-day max, 24 history), lockout (5 attempts, 30-min), Kerberos (10-hour TGT)
- **Default Domain Controllers Policy**: 25 user rights assignments, SMB/LDAP signing, secure channel encryption
- **Admins-01**: 10-min session lock, PowerShell script block logging + transcription, taskbar cleanup
- **Users-01**: Desktop lockdown (regedit, cmd, Run disabled), DelegatedAdmins exempted via deny security filtering
- **Workstations-01**: Full audit, autorun disabled, Windows Update 3 AM daily, NLA required, log sizing
- **AdminWorkstations-01**: Enhanced PAW -- all audit categories, PS transcription + module logging, command-line in 4688 events, 256 MB security log, Defender exclusions for JetBrains, RSAT startup script

### DSC Compliance

- **Apply-DscBaseline.ps1**: Second-layer validation of DC local state against GPO definitions
- **Single source of truth**: DSC configs read from settings.ps1, no value duplication
- **Kerberos validation**: Custom Script resource using secedit export (SecurityPolicyDsc doesn't support Kerberos natively)
- **Detailed drift output**: Reports specific non-compliant resources
- **Apply mode safety**: Warning banner + confirmation prompt required

### Documentation

- README.md with architecture, workflow, security model, and operations guide
- Per-GPO README files with settings tables and design rationale
- CLAUDE.md for AI assistant context