Public/Export-ADPrivilegedGroupDirectMember.ps1
|
<# .SYNOPSIS Exports direct membership of configured privileged Active Directory groups to JSON. .DESCRIPTION Checks the configured group RIDs in each domain of the selected forest and records the distinguished names of direct members. Nested groups are recorded as members without expanding their membership. Primary group membership is excluded. The backup records missing groups. Other directory lookup failures stop the export. After a successful export, the full backup path is saved in the module's AS2Go.json under ADPrivilegedGroupDirectMember. Import-ADPrivilegedGroupDirectMember offers this backup when run without a path. .PARAMETER Path Specifies the destination JSON file. The destination must not already exist. If omitted, saves to $Script:AS2GOConfigDir\AS2Go-<root-domain>MemberShipBackup-yyyyMMdd-HHmmss.json. The name uses the forest root domain's DNS name and the local date and time. .PARAMETER Forest Specifies the forest DNS name. Defaults to the forest of the current user. .PARAMETER ConfigPath Specifies the AS2Go JSON configuration containing the PriviledgeGroupRIDs setting. Defaults to the module's configured AS2Go.json file. .PARAMETER Silent Suppresses routine console output and diagnostic streams. Errors remain visible. .PARAMETER Preview Displays the planned steps without querying Active Directory or writing a backup. .EXAMPLE Export-ADPrivilegedGroupDirectMember Saves a timestamped backup in the AS2Go configuration directory and records its path. .EXAMPLE Export-ADPrivilegedGroupDirectMember -Path 'C:\Temp\ADGroupMembers.json' Exports direct memberships in the current user's forest using the module configuration. .OUTPUTS None. The function writes the backup to the specified JSON file. .NOTES Requires the ActiveDirectory PowerShell module for export. .LINK Import-ADPrivilegedGroupDirectMember .COMPONENT Category: Main Function .FUNCTIONALITY Backs up direct members of configured privileged groups across an Active Directory forest. Records missing groups in the backup and saves the latest backup path in the AS2Go configuration. #> function Export-ADPrivilegedGroupDirectMember { [CmdletBinding()] param( [ValidateNotNullOrEmpty()] [string]$Path, [string]$Forest, [ValidateNotNullOrEmpty()] [string]$ConfigPath = $Script:ConfigFile, [switch]$Silent, [switch]$Preview ) if ($Preview) { Show-AS2GoPreview -FunctionName 'Export-ADPrivilegedGroupDirectMember' return } $info = Measure-FunctionRuntime -Begin try { $ErrorActionPreference = 'Stop' if ($Silent) { $WarningPreference = 'SilentlyContinue' $VerbosePreference = 'SilentlyContinue' $DebugPreference = 'SilentlyContinue' $InformationPreference = 'SilentlyContinue' $ProgressPreference = 'SilentlyContinue' } else { Write-AS2GoOutput -Type Header -Message 'Export Privileged Group Memberships' Write-AS2GoOutput -Type H1 -Message $((Get-Help (Get-FunctionName)).Functionality) } $Config = Get-Content -LiteralPath $ConfigPath -Raw | ConvertFrom-Json $RidSettings = @($Config.DefaultParameter.Setting | Where-Object { $_.Name -eq 'PriviledgeGroupRIDs' }) if ($RidSettings.Count -ne 1 -or $RidSettings[0].Value -isnot [string]) { throw "Expected exactly one PriviledgeGroupRIDs string setting in $ConfigPath." } $GroupRids = @( foreach ($Token in ($RidSettings[0].Value -split ',')) { if ($Token -notmatch "^\s*(?:'([0-9]+)'|([0-9]+))\s*$") { throw "Invalid RID entry in PriviledgeGroupRIDs: $Token" } $RidText = if ($Matches[1]) { $Matches[1] } else { $Matches[2] } $ParsedRid = [uint32]0 if (-not [uint32]::TryParse($RidText, [ref]$ParsedRid) -or $ParsedRid -eq 0) { throw "RID must be a positive 32-bit unsigned integer: $RidText" } $ParsedRid } ) | Sort-Object -Unique $ForestParameters = @{} if ($Forest) { $ForestParameters.Identity = $Forest } Import-Module -Name ActiveDirectory -Scope Local $ForestInfo = Get-ADForest @ForestParameters if (-not $Path) { $Timestamp = Get-Date -Format 'yyyy-MM-dd_HHmmss' $BackupName = "AS2Go-$($ForestInfo.RootDomain)-PrivilegedGroupDirectMembers-$Timestamp.json" $Path = Join-Path -Path $Script:AS2GOConfigDir -ChildPath $BackupName } $Domains = @( foreach ($DomainName in ($ForestInfo.Domains | Sort-Object)) { $Domain = Get-ADDomain -Identity $DomainName -Server $DomainName $DomainController = Get-ADDomainController -Discover -DomainName $DomainName -Writable $Server = [string](@($DomainController.HostName)[0]) if ([string]::IsNullOrWhiteSpace($Server)) { throw "No domain controller hostname was returned for $DomainName." } $DomainSid = $Domain.DomainSID.Value $Groups = @( foreach ($Rid in $GroupRids) { $Sid = if ($Rid -in 548, 549, 550, 551) { "S-1-5-32-$Rid" } else { "$DomainSid-$Rid" } try { $Group = Get-ADGroup -Identity $Sid -Server $Server -Properties member [pscustomobject]@{ Rid = $Rid Sid = $Sid Name = $Group.Name DistinguishedName = $Group.DistinguishedName Status = 'Exported' Members = @($Group.member | Sort-Object) } } catch [Microsoft.ActiveDirectory.Management.ADIdentityNotFoundException] { Write-Warning "Group $Sid does not exist in $DomainName." [pscustomobject]@{ Rid = $Rid Sid = $Sid Name = $null DistinguishedName = $null Status = 'Missing' Members = @() } } } ) [pscustomobject]@{ Domain = [string]$DomainName DomainSid = $DomainSid Groups = $Groups } } ) [pscustomobject]@{ SchemaVersion = 1 Forest = $ForestInfo.Name ExportedAtUtc = [DateTime]::UtcNow.ToString('o') MembershipType = 'DirectMemberAttribute' Domains = $Domains } | ConvertTo-Json -Depth 8 | Out-File -LiteralPath $Path -Encoding utf8 -NoClobber $BackupPath = (Resolve-Path -LiteralPath $Path).ProviderPath Write-Verbose "Exported direct memberships for $($Domains.Count) domains to $BackupPath." Set-ASConfig -Setting 'ADPrivilegedGroupDirectMember' -Value $BackupPath Write-AS2GoOutput -Type Success -Message "Exported direct Group Membership to $BackupPath" } finally { Measure-FunctionRuntime -End -Details $info } } |