Private/Apply.ps1
|
# Applying a plan: backup and rollback files first, then per batch: drift check -> PATCH -> verify. Every outcome is logged. function Get-STMDataRoot { $root = $script:STM.Settings.DataRoot if (-not $root) { $base = if ($env:LOCALAPPDATA) { $env:LOCALAPPDATA } else { Join-Path $HOME '.local/share' } $root = Join-Path $base 'IntuneScopeTagManager' } if (-not (Test-Path -LiteralPath $root)) { New-Item -ItemType Directory -Path $root -Force | Out-Null } return $root } function Write-STMAudit { param([Parameter(Mandatory)][string]$Event, [hashtable]$Data) $entry = [ordered]@{ timeUtc = [DateTime]::UtcNow.ToString('o'); event = $Event; tenant = $script:STM.TenantId; account = $script:STM.Account; computer = [Environment]::MachineName } if ($Data) { foreach ($k in $Data.Keys) { $entry[$k] = $Data[$k] } } $line = $entry | ConvertTo-Json -Compress -Depth 6 Add-Content -LiteralPath (Join-Path (Get-STMDataRoot) 'audit.log') -Value $line -Encoding utf8 } function ConvertTo-STMLegacyCsvRows { # Same columns as the existing Update-IntuneScopeTags-Bulk.ps1 so a rollback file also works with the old script. param([object[]]$Items, [ValidateSet('Before', 'After')][string]$Side, [string]$Note) foreach ($i in $Items) { [pscustomobject][ordered]@{ ObjectType = $i.Type; ObjectId = $i.Id; DisplayName = $i.Name ScopeTags = (@($i.$Side) -join ';'); Mode = 'Replace'; Notes = $Note } } } function Export-STMPlan { <# Writes a plan as JSON (machine) and CSV (change board review). #> param([Parameter(Mandatory)]$Plan, [Parameter(Mandatory)][string]$Directory) if (-not (Test-Path -LiteralPath $Directory)) { New-Item -ItemType Directory -Path $Directory -Force | Out-Null } $json = Join-Path $Directory "ScopeTagPlan_$($Plan.PlanId).json" $csv = Join-Path $Directory "ScopeTagPlan_$($Plan.PlanId).csv" $Plan | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath $json -Encoding utf8 $Plan.Items | ForEach-Object { [pscustomobject][ordered]@{ State = $_.State; ObjectType = $_.Type; TypeLabel = $_.TypeLabel; ObjectId = $_.Id; DisplayName = $_.Name; Platform = $_.Platform CurrentScopeTags = ($_.BeforeNames -join ';'); NewScopeTags = ($_.AfterNames -join ';') Added = (($_.Added | ForEach-Object { Get-STMTagName $_ }) -join ';'); Removed = (($_.Removed | ForEach-Object { Get-STMTagName $_ }) -join ';') CurrentScopeTagIds = ($_.Before -join ';'); NewScopeTagIds = ($_.After -join ';') LosesVisibility = ($_.VisibilityLost -join '; '); GainsVisibility = ($_.VisibilityGained -join '; ') Issues = ($_.Issues -join '; '); Warnings = ($_.Warnings -join '; '); Notes = $_.Note } } | Export-Csv -LiteralPath $csv -NoTypeInformation -Encoding utf8 return [pscustomobject]@{ Json = $json; Csv = $csv; Hash = $Plan.Hash } } function Import-STMPlanFile { <# Loads a plan JSON (for example one approved by change control) and checks its fingerprint. #> param([Parameter(Mandatory)][string]$Path) $plan = Get-Content -LiteralPath $Path -Raw | ConvertFrom-STMJson $expected = $plan.Hash $actual = Get-STMPlanHash -Plan $plan if ($expected -ne $actual) { throw "Plan file was edited after it was created (fingerprint $actual, expected $expected). Rebuild the plan." } if ($script:STM.TenantId -and $plan.Tenant -and $plan.Tenant -ne $script:STM.TenantId) { throw "Plan was built for tenant $($plan.Tenant) but you are signed in to $($script:STM.TenantId)." } $script:STM.Plans[$plan.PlanId] = $plan return $plan } function Start-STMRun { param([Parameter(Mandatory)]$Plan, [string]$Confirmation) if ($script:STM.Mode -ne 'ReadWrite') { throw 'Signed in read-only. Reconnect in write mode to apply changes.' } if (-not $Plan.CanApply) { throw "This plan cannot be applied: $(@($Plan.PlanIssues) -join ' ') Ready items: $($Plan.Summary.Ready)." } if ((Get-STMPlanHash -Plan $Plan) -ne $Plan.Hash) { throw 'Plan fingerprint changed; rebuild the plan.' } $ready = @($Plan.Items | Where-Object State -eq 'Ready') # Re-check the rules with this session's settings rather than trusting the plan's own verdict. $recheck = [System.Collections.Generic.List[string]]::new() $cap = [int]$script:STM.Settings.MaxChangesPerRun if ($cap -gt 0 -and $ready.Count -gt $cap -and -not ($Plan.OverrideCap -and $Plan.OverrideReason)) { $recheck.Add("$($ready.Count) changes exceed the per-run cap of $cap and the plan has no override with a reason.") } $protected = Get-STMProtectedTagIds $pm = Get-STMProtectedTagProblem -Protected $protected if ($pm -and $script:STM.Settings.ProtectedTagMissingBehavior -eq 'Block') { $recheck.Add($pm) } foreach ($it in $ready) { $b = @($it.Before | Where-Object { "$_" -ne '' }); $a = @($it.After | Where-Object { "$_" -ne '' }) if (@($b + $a | Where-Object { $protected.Ids -contains $_ }).Count) { $recheck.Add("$($it.Key) involves a protected scope tag.") } if (-not $a.Count -and -not $Plan.AllowNoExplicitTags) { $recheck.Add("$($it.Key) would be left with no scope tags and the plan does not allow that.") } if ($a.Count -gt 100) { $recheck.Add("$($it.Key) would have more than 100 scope tags.") } if ($script:STM.AppOnly) { $wd = Get-STMTypeDef -Key $it.Type $ws = if ($wd -and $wd.PSObject.Properties['writeScope']) { [string]$wd.writeScope } else { '' } if ($ws -and -not (Test-STMAppHasWrite -Permission $ws)) { $recheck.Add("$($it.Key): the app registration lacks the $ws application permission.") } } if (@($it.Issues | Where-Object { $_ }).Count) { $recheck.Add("$($it.Key) has unresolved issues.") } } if ($recheck.Count) { throw "This plan cannot be applied: $(@($recheck | Select-Object -First 5) -join ' ')" } $expected = "APPLY $($ready.Count)" if ($Confirmation -cne $expected) { throw "Type '$expected' to confirm." } if ($script:STM.ActiveRun -and -not $script:STM.Runs[$script:STM.ActiveRun].Done) { throw 'Another run is in progress in this session.' } $runId = "{0}-{1}" -f [DateTime]::UtcNow.ToString('yyyyMMdd-HHmmss'), ([guid]::NewGuid().ToString('N').Substring(0, 6)) $dir = Join-Path (Join-Path (Get-STMDataRoot) 'Runs') $runId New-Item -ItemType Directory -Path $dir -Force | Out-Null # Backup and rollback files exist before the first write. $Plan | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath (Join-Path $dir 'plan.json') -Encoding utf8 $ready | Select-Object Key, Type, Id, Name, Before, BeforeNames | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath (Join-Path $dir 'backup.json') -Encoding utf8 ConvertTo-STMLegacyCsvRows -Items $ready -Side Before -Note "Rollback of run $runId" | Export-Csv -LiteralPath (Join-Path $dir 'rollback.csv') -NoTypeInformation -Encoding utf8 $run = [ordered]@{ RunId = $runId; PlanId = $Plan.PlanId; PlanHash = $Plan.Hash; Folder = $dir; StartedUtc = [DateTime]::UtcNow.ToString('o') Items = $ready; Cursor = 0; Results = [System.Collections.Generic.List[object]]::new(); Done = $false; Cancelled = $false Counts = [ordered]@{ Applied = 0; AppliedUnverified = 0; SkippedDrift = 0; SkippedProtected = 0; Failed = 0; NoChange = 0 } } $script:STM.Runs[$runId] = $run $script:STM.ActiveRun = $runId Write-STMAudit -Event 'RunStarted' -Data @{ runId = $runId; planId = $Plan.PlanId; planHash = $Plan.Hash; items = $ready.Count; folder = $dir } Add-Content -LiteralPath (Join-Path $dir 'run.log') -Value "$([DateTime]::UtcNow.ToString('o')) Run $runId started by $($script:STM.Account) for plan $($Plan.PlanId) ($($ready.Count) objects)" -Encoding utf8 return Get-STMRunView -RunId $runId } function Get-STMWriteBody { param($Item, $Def, [string[]]$Tags) $prop = if ($Def.PSObject.Properties['tagProperty']) { $Def.tagProperty } else { 'roleScopeTagIds' } $body = [ordered]@{} if ($Def.writeStrategy -eq 'PatchWithODataType' -and $Item.ODataType) { $body['@odata.type'] = $Item.ODataType } $body[$prop] = [string[]]@($Tags | Where-Object { "$_" -ne '' }) return $body } function Step-STMRun { <# Processes the next batch (up to 20 objects): re-read, compare with the plan's "before", write, re-read to verify. #> param([Parameter(Mandatory)][string]$RunId, [int]$BatchSize = 20) $run = $script:STM.Runs[$RunId] if (-not $run) { throw "Unknown run $RunId" } if ($run.Done) { return Get-STMRunView -RunId $RunId } $chunk = @($run.Items | Select-Object -Skip $run.Cursor -First $BatchSize) if (-not $chunk.Count) { return (Complete-STMRun -RunId $RunId) } $protected = (Get-STMProtectedTagIds).Ids # 1. Drift check: the live object must still match what the plan saw. $live = Get-STMLiveObject -Refs @($chunk | ForEach-Object { @{ Type = $_.Type; Id = $_.Id } }) $toWrite = [System.Collections.Generic.List[object]]::new() foreach ($i in $chunk) { $l = $live[$i.Key] $res = [ordered]@{ TimeUtc = [DateTime]::UtcNow.ToString('o'); Key = $i.Key; Type = $i.Type; Id = $i.Id; Name = $i.Name; Before = ($i.Before -join ';'); Planned = ($i.After -join ';'); Live = ''; Result = ''; Detail = '' } if (-not $l.Row) { $res.Result = 'Failed'; $res.Detail = "Could not re-read object: $($l.Error)" } else { $now = @($l.Row.TagIds) $res.Live = $now -join ';' if (@($now | Where-Object { $protected -contains $_ }).Count) { $res.Result = 'SkippedProtected'; $res.Detail = 'Object now carries a protected tag' } elseif ((@($now) -join ',') -ne (@($i.Before) -join ',')) { if ((@($now) -join ',') -eq (@($i.After) -join ',')) { $res.Result = 'NoChange'; $res.Detail = 'Already has the planned tags' } else { $res.Result = 'SkippedDrift'; $res.Detail = "Changed since the plan was built (now: $((@($now | ForEach-Object { Get-STMTagName $_ })) -join ', ')). Rebuild the plan for this object." } } else { $i | Add-Member -NotePropertyName LiveODataType -NotePropertyValue $l.Row.ODataType -Force; $toWrite.Add($i) } } if ($res.Result) { $run.Results.Add([pscustomobject]$res) } else { $i | Add-Member -NotePropertyName PendingResult -NotePropertyValue $res -Force } } # 2. Write. if ($toWrite.Count) { $reqs = @(foreach ($i in $toWrite) { $def = Get-STMTypeDef -Key $i.Type $item = [pscustomobject]@{ ODataType = if ($i.LiveODataType) { $i.LiveODataType } else { $i.ODataType } } @{ id = $i.Key; method = 'PATCH'; url = "/$($def.path)/$($i.Id)"; body = (Get-STMWriteBody -Item $item -Def $def -Tags $i.After) } }) $w = Invoke-STMBatch -Requests $reqs $written = [System.Collections.Generic.List[object]]::new() foreach ($i in $toWrite) { $r = $w[$i.Key] if ($r -and $r.status -ge 200 -and $r.status -lt 300) { $written.Add($i) } else { $i.PendingResult.Result = 'Failed' $err = if ($r) { $r.error } else { 'No response' } if ($err -match 'MultiAdminApprovalRequired') { $err += '. This tenant requires Multi Admin Approval for this change; request approval in the Intune admin center.' } $i.PendingResult.Detail = $err $run.Results.Add([pscustomobject]$i.PendingResult) } } # 3. Verify. if ($written.Count) { $check = Get-STMLiveObject -Refs @($written | ForEach-Object { @{ Type = $_.Type; Id = $_.Id } }) foreach ($i in $written) { $c = $check[$i.Key] $got = if ($c.Row) { @($c.Row.TagIds) } else { @() } $i.PendingResult.Live = $got -join ';' if ($c.Row -and ((@($got) -join ',') -eq (@($i.After) -join ','))) { $i.PendingResult.Result = 'Applied'; $i.PendingResult.Detail = 'Written and verified' } else { $i.PendingResult.Result = 'AppliedUnverified'; $i.PendingResult.Detail = 'Write accepted; read-back did not match yet (Intune can lag). Final verification runs at the end.' } $run.Results.Add([pscustomobject]$i.PendingResult) if ($c.Row -and $script:STM.Inventory.ContainsKey($i.Key)) { $script:STM.Inventory[$i.Key] = $c.Row } } } } $run.Cursor += $chunk.Count Save-STMRunResults -RunId $RunId if ($run.Cursor -ge $run.Items.Count) { return (Complete-STMRun -RunId $RunId) } return Get-STMRunView -RunId $RunId } function Complete-STMRun { param([Parameter(Mandatory)][string]$RunId, [int]$VerifyAttempts = 3, [int]$VerifyDelaySeconds = 3) $run = $script:STM.Runs[$RunId] $pending = @($run.Results | Where-Object Result -eq 'AppliedUnverified') for ($a = 1; $a -le $VerifyAttempts -and $pending.Count; $a++) { Start-Sleep -Seconds $VerifyDelaySeconds $check = Get-STMLiveObject -Refs @($pending | ForEach-Object { @{ Type = $_.Type; Id = $_.Id } }) foreach ($p in $pending) { $c = $check[$p.Key] if ($c.Row -and ((@($c.Row.TagIds) -join ';') -eq $p.Planned)) { $p.Result = 'Applied'; $p.Detail = "Written and verified (attempt $a)"; $p.Live = $p.Planned } } $pending = @($run.Results | Where-Object Result -eq 'AppliedUnverified') } $run.Done = $true $run.FinishedUtc = [DateTime]::UtcNow.ToString('o') Save-STMRunResults -RunId $RunId $v = Get-STMRunView -RunId $RunId Write-STMAudit -Event 'RunFinished' -Data @{ runId = $RunId; counts = $v.Counts; cancelled = $run.Cancelled } Add-Content -LiteralPath (Join-Path $run.Folder 'run.log') -Value "$([DateTime]::UtcNow.ToString('o')) Run finished: $(($v.Counts.GetEnumerator() | ForEach-Object { "$($_.Key)=$($_.Value)" }) -join ' ')" -Encoding utf8 return $v } function Stop-STMRun { param([Parameter(Mandatory)][string]$RunId) $run = $script:STM.Runs[$RunId] if (-not $run.Done) { $run.Cancelled = $true foreach ($i in @($run.Items | Select-Object -Skip $run.Cursor)) { $run.Results.Add([pscustomobject][ordered]@{ TimeUtc = [DateTime]::UtcNow.ToString('o'); Key = $i.Key; Type = $i.Type; Id = $i.Id; Name = $i.Name; Before = ($i.Before -join ';'); Planned = ($i.After -join ';'); Live = ''; Result = 'NotRun'; Detail = 'Run stopped before this object' }) } $run.Cursor = $run.Items.Count return (Complete-STMRun -RunId $RunId -VerifyAttempts 1 -VerifyDelaySeconds 1) } return Get-STMRunView -RunId $RunId } function Save-STMRunResults { param([Parameter(Mandatory)][string]$RunId) $run = $script:STM.Runs[$RunId] $run.Results | Export-Csv -LiteralPath (Join-Path $run.Folder 'results.csv') -NoTypeInformation -Encoding utf8 $run.Results | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath (Join-Path $run.Folder 'results.json') -Encoding utf8 } function Get-STMRunView { param([Parameter(Mandatory)][string]$RunId) $run = $script:STM.Runs[$RunId] $counts = [ordered]@{} foreach ($k in 'Applied', 'AppliedUnverified', 'NoChange', 'SkippedDrift', 'SkippedProtected', 'Failed', 'NotRun') { $counts[$k] = @($run.Results | Where-Object Result -eq $k).Count } [pscustomobject][ordered]@{ RunId = $run.RunId; PlanId = $run.PlanId; Folder = $run.Folder; StartedUtc = $run.StartedUtc; FinishedUtc = $run.FinishedUtc Total = $run.Items.Count; Processed = [math]::Min($run.Cursor, $run.Items.Count); Done = $run.Done; Cancelled = $run.Cancelled Counts = $counts; Results = @($run.Results) } } function Get-STMRunHistory { $dir = Join-Path (Get-STMDataRoot) 'Runs' if (-not (Test-Path -LiteralPath $dir)) { return @() } Get-ChildItem -LiteralPath $dir -Directory | Sort-Object Name -Descending | ForEach-Object { $res = @(); $plan = $null $rf = Join-Path $_.FullName 'results.json'; $pf = Join-Path $_.FullName 'plan.json' if (Test-Path $rf) { $res = @(Get-Content -LiteralPath $rf -Raw | ConvertFrom-Json) } if (Test-Path $pf) { $plan = Get-Content -LiteralPath $pf -Raw | ConvertFrom-STMJson } [pscustomobject][ordered]@{ RunId = $_.Name; Folder = $_.FullName; PlanTitle = if ($plan) { $plan.Title } else { '' }; Tenant = if ($plan) { $plan.Tenant } else { '' } Applied = @($res | Where-Object { $_.Result -in 'Applied', 'AppliedUnverified' }).Count Failed = @($res | Where-Object Result -eq 'Failed').Count Skipped = @($res | Where-Object { $_.Result -like 'Skipped*' }).Count HasRollback = Test-Path (Join-Path $_.FullName 'rollback.csv') } } } function New-STMRollbackOperations { <# Rollback = put every object this run changed back to its "before" tags (Replace). Objects the run did not change are left out. #> param([Parameter(Mandatory)][string]$RunId) $dir = Join-Path (Join-Path (Get-STMDataRoot) 'Runs') $RunId $results = @(Get-Content -LiteralPath (Join-Path $dir 'results.json') -Raw | ConvertFrom-Json) $changed = @($results | Where-Object { $_.Result -in 'Applied', 'AppliedUnverified' }) foreach ($c in $changed) { [pscustomobject]@{ Type = $c.Type; Id = $c.Id; Mode = 'Replace'; Tags = @("$($c.Before)" -split ';' | Where-Object { $_ }); Note = "Rollback of run $RunId"; Source = "rollback:$RunId" } } } |