<#
.SYNOPSIS
    Runs every SecurityInsight Container Apps job of an install ONCE, in schedule order, and reports each run.

.DESCRIPTION
    Reads the install's config (config/SecurityInsight.custom.ps1, without running it) for its subscription and resource
    group, lists the Container Apps jobs there and runs them the way the daily schedule would: jobs that start at the
    same time of day run together (in parallel), and each group waits for the one before it -- profilers before Risk
    Analysis, Risk Analysis before the trend. Each execution's outcome and duration is reported; exit code 1 when any
    run did not succeed (or did not finish within -TimeoutMinutes), 0 otherwise.

    Left out: the updater job (it changes the install; -IncludeUpdater runs it) and event-triggered jobs (they run when
    work arrives). -PlanOnly prints the order and starts nothing.

    Changes nothing but starting the jobs. Needs no PowerShell module (plain REST); signs in as the install's own
    identity from its config, or as the service principal certificate named in SI_DIAGNOSTICS_APPID /
    SI_DIAGNOSTICS_TENANTID / SI_DIAGNOSTICS_CERTTHUMBPRINT (-SignIn). The identity needs to start jobs in the
    resource group (Contributor there).

.EXAMPLE
    ./diagnostics/Invoke-SIJobsOnce.ps1 -PlanOnly
.EXAMPLE
    ./diagnostics/Invoke-SIJobsOnce.ps1 -TimeoutMinutes 180

.LINK
    https://invardia.com/docs/si/scripts/Invoke-SIJobsOnce/

.NOTES
    Requirements:
      PowerShell 7 (pwsh). Windows PowerShell 5.1 is refused at once (#Requires -Version 7.0).
      Role: Container Apps Jobs Operator (or Contributor) -- on the install's resource group
      Hosts: *.blob.core.windows.net, *.queue.core.windows.net, *.table.core.windows.net, *.vault.azure.net, 169.254.169.254, api.loganalytics.io, graph.microsoft.com, invardia.com, login.microsoftonline.com, management.azure.com, monitor.azure.com, storage.azure.com, vault.azure.net
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [string]$ConfigPath,
    [string]$ResourceGroup,
    [string]$SubscriptionId,
    [string[]]$Only = @(),
    [string[]]$Exclude = @(),
    [switch]$IncludeUpdater,
    [switch]$PlanOnly,
    [int]$TimeoutMinutes = 120,
    [int]$PollSeconds = 30,
    [ValidateSet('Auto', 'AzContext', 'Config')][string]$SignIn = 'Auto',
    [switch]$PassThru,
    # Tests only: replacements for the calls that leave this process (Arm, LaQuery, Graph, Now, Sleep, Print).
    [Parameter(DontShow)][System.Collections.IDictionary]$Seams
)

#Requires -Version 7.0
# SecurityInsight 3.0.79 -- Invoke-SIJobsOnce.ps1, standalone (Community edition). Built 2026-11-09T20:28:39Z from commit c1472e2f4c240c971c9559f07eef7e794b322001, source SOLUTIONS/SecurityInsight/diagnostics/Invoke-SIJobsOnce.ps1,
# by release/Build-SISupportScripts.ps1 (framework SUPPORT-DL-1). Download: Invoke-WebRequest https://invardia.com/support/si/Invoke-SIJobsOnce.ps1 -OutFile Invoke-SIJobsOnce.ps1
# It carries the 20 SecurityInsight file(s) the script loads (listed in $__siSupportFiles below, readable, each line
# prefixed with "|"); at run time it writes them to a private temporary folder, checks each SHA-256, runs the original
# script from there with your parameters, and removes the folder. No PowerShell modules are needed.
$script:SIScriptVersion = '3.0.79'   # SI #547: the version this copy reports first (stamped into its embedded setup/_shared/SI-ScriptRun.ps1 too)
$__siSupportVersion = '3.0.79'
$__siSupportEntry = 'diagnostics/Invoke-SIJobsOnce.ps1'
$__siSupportFiles = [ordered]@{}
$__siSupportFiles['diagnostics/Invoke-SIJobsOnce.ps1'] = @{ Sha256 = '6c51e61512a460266f53ed5b9222d27a1f0d283ded148805a9c37a2646d2be5a'; Text = @'
|<#
|.SYNOPSIS
|    Runs every SecurityInsight Container Apps job of an install ONCE, in schedule order, and reports each run.
|
|.DESCRIPTION
|    Reads the install's config (config/SecurityInsight.custom.ps1, without running it) for its subscription and resource
|    group, lists the Container Apps jobs there and runs them the way the daily schedule would: jobs that start at the
|    same time of day run together (in parallel), and each group waits for the one before it -- profilers before Risk
|    Analysis, Risk Analysis before the trend. Each execution's outcome and duration is reported; exit code 1 when any
|    run did not succeed (or did not finish within -TimeoutMinutes), 0 otherwise.
|
|    Left out: the updater job (it changes the install; -IncludeUpdater runs it) and event-triggered jobs (they run when
|    work arrives). -PlanOnly prints the order and starts nothing.
|
|    Changes nothing but starting the jobs. Needs no PowerShell module (plain REST); signs in as the install's own
|    identity from its config, or as the service principal certificate named in SI_DIAGNOSTICS_APPID /
|    SI_DIAGNOSTICS_TENANTID / SI_DIAGNOSTICS_CERTTHUMBPRINT (-SignIn). The identity needs to start jobs in the
|    resource group (Contributor there).
|
|.EXAMPLE
|    ./diagnostics/Invoke-SIJobsOnce.ps1 -PlanOnly
|.EXAMPLE
|    ./diagnostics/Invoke-SIJobsOnce.ps1 -TimeoutMinutes 180
|
|.LINK
|    https://invardia.com/docs/si/scripts/Invoke-SIJobsOnce/
|#>
|[CmdletBinding(SupportsShouldProcess)]
|param(
|    [string]$ConfigPath,
|    [string]$ResourceGroup,
|    [string]$SubscriptionId,
|    [string[]]$Only = @(),
|    [string[]]$Exclude = @(),
|    [switch]$IncludeUpdater,
|    [switch]$PlanOnly,
|    [int]$TimeoutMinutes = 120,
|    [int]$PollSeconds = 30,
|    [ValidateSet('Auto', 'AzContext', 'Config')][string]$SignIn = 'Auto',
|    [switch]$PassThru,
|    # Tests only: replacements for the calls that leave this process (Arm, LaQuery, Graph, Now, Sleep, Print).
|    [Parameter(DontShow)][System.Collections.IDictionary]$Seams
|)
|
|#Requires -Version 7.0   # after the help and the param block: before the help, it hides the help from Get-Help
|# framework section 12.7 / 12.10: the documentation link first, a transcript of the run, -WhatIf writes nothing
|. ([IO.Path]::Combine((Split-Path -Parent $PSScriptRoot), 'setup', '_shared', 'SI-ScriptRun.ps1'))
|$siRun = Start-SIScriptRun -Script 'Invoke-SIJobsOnce' -Quiet:([bool]$PSBoundParameters.ContainsKey('Seams'))
|if ($WhatIfPreference) { $PlanOnly = $true }   # -WhatIf = the plan: no job is started
|try {
|$ErrorActionPreference = 'Stop'
|. ([IO.Path]::Combine($PSScriptRoot, '_SIInstallDiagnostics.ps1'))
|if (-not $ConfigPath) { $ConfigPath = [IO.Path]::Combine((Split-Path -Parent $PSScriptRoot), 'config', 'SecurityInsight.custom.ps1') }
|
|$values = @{}
|if ((-not $ResourceGroup -or -not $SubscriptionId) -or (Test-Path -LiteralPath $ConfigPath)) { $values = Read-SIInstallConfigValues -Path $ConfigPath }
|$target = Get-SIInstallTargetFromConfig -Values $values
|if ($SubscriptionId) { $target.SubscriptionId = $SubscriptionId }
|if ($ResourceGroup) { $target.ResourceGroup = $ResourceGroup }
|if (-not $target.SubscriptionId -or -not $target.ResourceGroup) { throw 'The subscription and resource group of the install are not known: give -ConfigPath, or -SubscriptionId and -ResourceGroup.' }
|$rgId = '/subscriptions/{0}/resourceGroups/{1}' -f $target.SubscriptionId, $target.ResourceGroup
|
|if (-not $Seams) { $null = Initialize-SIDiagnosticsSignIn -SignIn $SignIn -Values $values }
|$s = Merge-SIDiagnosticsSeams -Seams $Seams
|$jobs = @(& $s.Arm 'GET' ($rgId + '/providers/Microsoft.App/jobs') $script:SIDiagJobApi -List:$true $null | Where-Object { $_ })
|$plan = Get-SIJobRunPlan -Jobs $jobs -IncludeUpdater:$IncludeUpdater -Only $Only -Exclude $Exclude
|
|& $s.Print ('== SecurityInsight jobs in {0}: {1} to run in {2} group(s)' -f $target.ResourceGroup, @($plan.Groups | ForEach-Object { $_.Jobs }).Count, @($plan.Groups).Count) 'Cyan'
|$i = 0
|foreach ($g in @($plan.Groups)) { $i++; & $s.Print ('  {0,2}. {1,-6} {2}' -f $i, $g.At, (@($g.Jobs | ForEach-Object Name) -join ', ')) '' }
|foreach ($k in @($plan.Skipped)) { & $s.Print ('  left out: {0} ({1})' -f $k.Name, $k.Why) 'DarkGray' }
|if (-not @($plan.Groups).Count) { & $s.Print '  no job to run.' 'Red'; exit 1 }
|if ($PlanOnly) { if ($PassThru) { $plan }; exit 0 }
|
|$r = Invoke-SIJobRunOnce -Plan $plan -Seams $s -PollSeconds $PollSeconds -TimeoutMinutes $TimeoutMinutes
|if ($PassThru) { $r }
|exit $(if ($r.Ok) { 0 } else { 1 })
|} finally { Stop-SIScriptRun -Run $siRun }
'@ }
$__siSupportFiles['setup/_shared/SI-ScriptRun.ps1'] = @{ Sha256 = 'a5c4d788d516521639611af43e1b88458216ce58bdb455885cac8e2a568afbd2'; Text = @'
|#Requires -Version 5.1
|<#
|    EVERY SCRIPT A PERSON RUNS (framework DOCS/REQUIREMENTS.md section 12.7 SCRIPT-DOC-1 + section 12.10 SECURITY-PACK-1; SI #481 / #484).
|    One helper, called first by each such script:
|
|      $siRun = Start-SIScriptRun -Script '<Script>'
|      try { ...the script... } finally { Stop-SIScriptRun -Run $siRun }
|
|    Start-SIScriptRun prints, as the script's FIRST line (SI #547, owner 2026-10-10: "do you provide the version in all
|    scripts, so i can troubleshoot better"):
|        <Script> version <version> - documentation: https://invardia.com/docs/si/scripts/<Script>/
|    (the page Invardia renders from the script's <Script>.doc.json). The transcript is started BEFORE that line is printed,
|    so the same line is also the first line of the transcript. The version (Get-SIScriptVersion), in this order:
|        1. the version stamped into a PUBLISHED copy: release\Build-SISupportScripts.ps1 rewrites the
|           $script:SIScriptVersionStamp line below in the copy of this file each self-contained script embeds;
|        2. the install / package / checkout this file sits in: BUILD.json (its display, e.g. 3.0.0-rc.12), else VERSION;
|        3. "unknown (not a released copy)".
|    It then says plainly when -WhatIf is on (nothing is changed). The transcript is a local file in ONE known folder:
|        Windows : %LOCALAPPDATA%\SecurityInsight\script-logs\<Script>-<yyyyMMdd-HHmmss>.log
|        others  : ~/.securityinsight/script-logs/<Script>-<yyyyMMdd-HHmmss>.log
|    Stop-SIScriptRun ends the transcript and prints its path. The transcript holds what the script printed -- the scripts
|    never print a secret value (section 12.10 "no secrets in, no secrets out"). A transcript that cannot be started (a host
|    without transcription, a read-only profile) is said and the script goes on: it never blocks the work.
|    The transcript and its folder are written even under -WhatIf (-WhatIf:$false): they are the record of what was
|    previewed, not a change to the customer's environment.
|    PowerShell 5.1: no ?. / ??, no ternary.
|#>
|
|# SI #547 -- the PUBLISH STAMP. Empty in the repository and the package; release\Build-SISupportScripts.ps1 writes the release
|# version here (Set-SIScriptVersionStamp) in the copy a self-contained script embeds. Keep this line's shape: the build
|# refuses to publish when it cannot find it.
|$script:SIScriptVersionStamp = '3.0.79'
|# the folder this helper lives in (setup\_shared) -- the solution root is two levels up
|$script:SIScriptRunHome = $PSScriptRoot
|
|function Get-SIScriptVersion {
|    <#
|        The version a person-run script reports. -Stamp (default: the publish stamp above) wins; else -SolutionRoot's
|        BUILD.json display / version, else its VERSION file; else 'unknown (not a released copy)'. Never throws.
|    #>
|    param([AllowEmptyString()][string]$Stamp = [string]$script:SIScriptVersionStamp, [AllowEmptyString()][string]$SolutionRoot = '')
|    if ("$Stamp".Trim()) { return "$Stamp".Trim() }
|    if (-not "$SolutionRoot".Trim() -and "$($script:SIScriptRunHome)".Trim()) {
|        try { $SolutionRoot = [IO.Path]::GetFullPath([IO.Path]::Combine([string]$script:SIScriptRunHome, '..', '..')) } catch { $SolutionRoot = '' }
|    }
|    if ("$SolutionRoot".Trim()) {
|        try {
|            # not [IO.Path]::Combine(..., 'BUILD.json'): the support-script builder embeds every data file a helper names that
|            # way, and a published copy must never carry the build machine's BUILD.json (its version comes from the stamp)
|            $bj = $SolutionRoot.TrimEnd('\', '/') + [IO.Path]::DirectorySeparatorChar + 'BUILD.json'
|            if ([IO.File]::Exists($bj)) {
|                $j = [IO.File]::ReadAllText($bj) | ConvertFrom-Json
|                if ("$($j.display)".Trim()) { return "$($j.display)".Trim() }
|                if ("$($j.version)".Trim()) { return "$($j.version)".Trim() }
|            }
|        } catch { }
|        try {
|            $vf = [IO.Path]::Combine($SolutionRoot, 'VERSION')
|            if ([IO.File]::Exists($vf)) { $v = ([IO.File]::ReadAllText($vf)).Trim(); if ($v) { return $v } }
|        } catch { }
|    }
|    'unknown (not a released copy)'
|}
|
|function Get-SIScriptFirstLine {
|    <# PURE. The first line of every person-run script: "<Script> version <v> - documentation: <link>". #>
|    param([Parameter(Mandatory)][string]$Script, [Parameter(Mandatory)][string]$Version)
|    $n = [IO.Path]::GetFileNameWithoutExtension($Script.Trim())
|    '{0} version {1} - documentation: {2}' -f $n, $Version, (Get-SIScriptDocUrl -Script $n)
|}
|
|function Get-SIScriptDocUrl {
|    <# PURE. The documentation page of a script (no .ps1, trailing slash -- confirmed by Invardia 2026-10-09). #>
|    param([Parameter(Mandatory)][string]$Script)
|    $n = ([IO.Path]::GetFileNameWithoutExtension($Script.Trim()))
|    'https://invardia.com/docs/si/scripts/{0}/' -f $n
|}
|
|function Get-SIScriptLogFolder {
|    <# PURE apart from reading the environment. The one known folder every script's transcript goes to. #>
|    if ($env:SI_SCRIPT_LOG_DIR) { return [string]$env:SI_SCRIPT_LOG_DIR }
|    if ($env:LOCALAPPDATA) { return [IO.Path]::Combine($env:LOCALAPPDATA, 'SecurityInsight', 'script-logs') }
|    $h = $HOME; if (-not $h) { $h = [Environment]::GetFolderPath('UserProfile') }
|    [IO.Path]::Combine($h, '.securityinsight', 'script-logs')
|}
|
|function Start-SIScriptRun {
|    <#
|        The first thing a script does. Returns the run (pass it to Stop-SIScriptRun). -WhatIf comes from the caller's
|        $WhatIfPreference; -Quiet (tests) prints nothing and starts no transcript.
|    #>
|    param([Parameter(Mandatory)][string]$Script, [switch]$Quiet, [bool]$WhatIfOn = [bool]$WhatIfPreference)
|    if ($env:SI_SCRIPT_RUN_QUIET -eq '1') { $Quiet = [switch]$true }      # tests: no banner, no transcript
|    $name = [IO.Path]::GetFileNameWithoutExtension($Script.Trim())
|    $ver = Get-SIScriptVersion
|    $run = [pscustomobject]@{ Script = $name; DocUrl = (Get-SIScriptDocUrl -Script $name); Version = $ver; FirstLine = (Get-SIScriptFirstLine -Script $name -Version $ver)
|                              Transcript = ''; Started = $false; WhatIf = $WhatIfOn; Quiet = [bool]$Quiet }
|    if ($Quiet) { return $run }
|    # the transcript FIRST (silently), so the version line below is the first line of the console AND of the transcript
|    $noTranscript = ''
|    try {
|        $dir = Get-SIScriptLogFolder
|        if (-not [IO.Directory]::Exists($dir)) { [void][IO.Directory]::CreateDirectory($dir) }
|        $path = [IO.Path]::Combine($dir, ('{0}-{1:yyyyMMdd-HHmmss}.log' -f $name, [datetime]::Now))
|        $null = Start-Transcript -LiteralPath $path -WhatIf:$false -ErrorAction Stop
|        $run.Transcript = $path; $run.Started = $true
|    } catch {
|        $noTranscript = $_.Exception.Message
|    }
|    Write-Host $run.FirstLine
|    if ($noTranscript) { Write-Host ('(no transcript of this run: {0})' -f $noTranscript) -ForegroundColor DarkGray }
|    if ($WhatIfOn) { Write-Host '-WhatIf: this run only reads and shows what it would change -- nothing is changed.' -ForegroundColor Yellow }
|    $run
|}
|
|function Stop-SIScriptRun {
|    <# The last thing a script does (in its finally block): ends the transcript and prints where it is. #>
|    param($Run)
|    if ($null -eq $Run -or $Run.Quiet) { return }
|    if ($Run.Started) {
|        try { $null = Stop-Transcript -ErrorAction Stop } catch { }
|        Write-Host ('Transcript of this run: {0}' -f $Run.Transcript)
|    }
|}
'@ }
$__siSupportFiles['diagnostics/_SIInstallDiagnostics.ps1'] = @{ Sha256 = 'ee9f8cc0d53b04cd32f07e1b5334f54f293126b03457096279c4788a5534eea4'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- the install diagnostics' shared engine: diagnostics/Test-SIInstall.ps1 (is this install healthy and
|    isolated?) and diagnostics/Invoke-SIJobsOnce.ps1 (run every engine job once, in schedule order).
|
|    Product scripts, usable at a customer: no environment value is written in here. Everything comes from the install's
|    own config file (config/SecurityInsight.custom.ps1), read WITHOUT running it -- the file may read Key Vault, and a
|    diagnostic must never do that.
|
|    Azure is reached over plain REST (engine/_shared/SI-AzRest.ps1: Log Analytics data plane, ARM, Resource Graph), so
|    no Az module is needed. EVERY call that leaves the process goes through a seam ($Seams: Arm, LaQuery, Graph, Now,
|    Sleep, Print), so the tests run the whole flow offline.
|
|    Ships in both editions; PS 5.1 and PowerShell 7 (Cloud Shell, Linux).
|#>
|
|$script:SIDiagRoot = Split-Path -Parent $PSScriptRoot
|# loaded unless the REAL file is (Get-SIAzRestState is only defined there; a test's global Invoke-SIArm stub is not it)
|if (-not (Get-Command -Name Get-SIAzRestState -ErrorAction SilentlyContinue)) {
|    . ([IO.Path]::Combine($script:SIDiagRoot, 'engine', '_shared', 'SI-AzRest.ps1'))
|}
|
|# A role that can CHANGE something. Read roles (Reader, Log Analytics Reader, AcrPull, Key Vault Secrets User) never count.
|$script:SIDiagWriteRolePattern = '(?i)(owner|contributor|monitoring metrics publisher|user access administrator|role based access control administrator)'
|$script:SIDiagFailedExitReasons = @('error', 'settings-error')
|$script:SIDiagJobApi = '2024-03-01'
|
|# ---------------------------------------------------------------------------------------------------------------------
|# The install's config, read without running it
|# ---------------------------------------------------------------------------------------------------------------------
|function Read-SIInstallConfigValues {
|    <#
|        PURE apart from reading the file. The constant top-level `$global:<Name> = <value>` assignments of a config file,
|        WITHOUT running it: strings, numbers, $true / $false, arrays of those. A value computed at run time (a Key Vault
|        lookup, a variable) is skipped. Later assignments win, as when the file runs.
|    #>
|    param([Parameter(Mandatory)][string]$Path)
|    if (-not (Test-Path -LiteralPath $Path)) { throw "The install's config file was not found: $Path" }
|    $tokens = $null; $errs = $null
|    $ast = [System.Management.Automation.Language.Parser]::ParseFile($Path, [ref]$tokens, [ref]$errs)
|    $out = @{}
|    $statements = @()
|    if ($ast.BeginBlock) { $statements += @($ast.BeginBlock.Statements) }
|    if ($ast.ProcessBlock) { $statements += @($ast.ProcessBlock.Statements) }
|    if ($ast.EndBlock) { $statements += @($ast.EndBlock.Statements) }
|    foreach ($s in $statements) {
|        if ($s -isnot [System.Management.Automation.Language.AssignmentStatementAst]) { continue }
|        if ([string]$s.Operator -ne 'Equals') { continue }
|        $left = $s.Left
|        while ($left -is [System.Management.Automation.Language.ConvertExpressionAst]) { $left = $left.Child }
|        if ($left -isnot [System.Management.Automation.Language.VariableExpressionAst]) { continue }
|        $name = [string]$left.VariablePath.UserPath
|        if ($name -notmatch '^(?i)global:(.+)$') { continue }
|        $key = $Matches[1]
|        $right = $s.Right
|        $expr = $null
|        if ($right -is [System.Management.Automation.Language.CommandExpressionAst]) { $expr = $right.Expression }
|        elseif ($right -is [System.Management.Automation.Language.PipelineAst] -and @($right.PipelineElements).Count -eq 1 -and
|                $right.PipelineElements[0] -is [System.Management.Automation.Language.CommandExpressionAst]) { $expr = $right.PipelineElements[0].Expression }
|        if (-not $expr) { continue }
|        try { $out[$key] = $expr.SafeGetValue() } catch { continue }
|    }
|    $out
|}
|
|function Get-SIInstallTargetFromConfig {
|    <#
|        PURE. What the diagnostics look at, from the config values: subscription, the install's resource group, the
|        workspace, the DCR resource group, the storage account, the identity, the configured DCR names and the grants
|        SecurityInsight documents for its identity.
|    #>
|    param([Parameter(Mandatory)][System.Collections.IDictionary]$Values)
|    $get = { param([string[]]$Names) foreach ($n in $Names) { $v = $Values[$n]; if ($null -ne $v -and "$v".Trim()) { return "$v".Trim() } }; '' }
|    $ws = & $get @('SI_WorkspaceResourceId')
|    $wsParts = if ($ws) { $ws.Trim('/') -split '/' } else { @() }
|    $sub = & $get @('SI_Bootstrap_SubscriptionId', 'SI_AzSubscriptionId')
|    if (-not $sub -and $wsParts.Count -ge 2) { $sub = $wsParts[1] }
|    $rg = & $get @('SI_Bootstrap_ResourceGroupName', 'SI_DcrResourceGroup', 'SI_WorkspaceResourceGroup')
|    if (-not $rg -and $wsParts.Count -ge 4) { $rg = $wsParts[3] }
|    if (-not $ws) {
|        $wsName = & $get @('SI_WorkspaceName'); $wsRg = & $get @('SI_WorkspaceResourceGroup')
|        if (-not $wsRg) { $wsRg = $rg }
|        if ($sub -and $wsRg -and $wsName) { $ws = '/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.OperationalInsights/workspaces/{2}' -f $sub, $wsRg, $wsName }
|    }
|    $dcrRg = & $get @('SI_DcrResourceGroup'); if (-not $dcrRg) { $dcrRg = $rg }
|    $stg = & $get @('SI_StorageAccount'); $stgRg = & $get @('SI_StorageResourceGroup'); if (-not $stgRg) { $stgRg = $dcrRg }
|    $stgId = if ($sub -and $stg) { '/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/{2}' -f $sub, $stgRg, $stg } else { '' }
|    # The configured DCR names: every SI_*Dcr* / *_DcrName* setting holding a name (not a {0} pattern).
|    $dcrNames = @($Values.Keys | Where-Object { $_ -match '(?i)^SI_.*dcr' -and $_ -notmatch '(?i)(pattern|resourcegroup|^SI_Dcr.*Rg)' } | Sort-Object |
|        ForEach-Object { [string]$Values[$_] } | Where-Object { $_ -and $_ -notmatch '[{}]' } | Select-Object -Unique)
|    $scopes = @($Values['SI_Bootstrap_IdentityReaderScopes'] | Where-Object { $_ })
|    if (-not $scopes.Count -and $sub) { $scopes = @("/subscriptions/$sub") }
|    [pscustomobject]@{
|        SubscriptionId       = $sub
|        ResourceGroup        = $rg
|        ResourceGroupId      = $(if ($sub -and $rg) { '/subscriptions/{0}/resourceGroups/{1}' -f $sub, $rg } else { '' })
|        WorkspaceResourceId  = $ws
|        DcrResourceGroup     = $dcrRg
|        DcrResourceGroupId   = $(if ($sub -and $dcrRg) { '/subscriptions/{0}/resourceGroups/{1}' -f $sub, $dcrRg } else { '' })
|        StorageAccountId     = $stgId
|        IdentityName         = (& $get @('SI_Bootstrap_ManagedIdentityName'))
|        IdentityClientId     = (& $get @('SI_ManagedIdentityClientId', 'SI_SPN_ManagedIdentityClientId', 'SI_UAMI_ClientId'))
|        DefenderWorkspaceId  = (& $get @('SI_DefenderWorkspaceResourceId'))
|        ReaderScopes         = $scopes
|        DcrNames             = $dcrNames
|        KeyVaultName         = (& $get @('SI_KeyVaultName', 'SpnKeyVaultName'))
|    }
|}
|
|function Get-SIInstallDocumentedWriteGrants {
|    <#
|        PURE. The WRITE grants SecurityInsight documents for its identity (the write rows of the container identity plan,
|        container/_shared/SI-ContainerConfig.ps1 Get-SIContainerIdentityGrantPlan, plus the two first-run schema grants of
|        setup/Grant-SIIdentity.ps1 -AllowSchemaCreate). Each is @{ Role; Scope }. A test pins this list to that plan.
|    #>
|    param([Parameter(Mandatory)]$Target)
|    $g = New-Object System.Collections.Generic.List[object]
|    $add = { param($r, $s) if ("$s".Trim()) { $g.Add([pscustomobject]@{ Role = $r; Scope = $s }) } }
|    & $add 'Monitoring Metrics Publisher' $Target.DcrResourceGroupId
|    foreach ($r in 'Storage Blob Data Contributor', 'Storage Queue Data Contributor', 'Storage Table Data Contributor') { & $add $r $Target.StorageAccountId }
|    & $add 'Monitoring Contributor' $Target.DcrResourceGroupId
|    & $add 'Log Analytics Contributor' $Target.WorkspaceResourceId
|    $g.ToArray()
|}
|
|function Test-SIScopeInside {
|    <# PURE. Is a scope the resource group (id) or inside it? #>
|    param([string]$Scope, [string]$ResourceGroupId)
|    if (-not $ResourceGroupId) { return $false }
|    $s = "$Scope".TrimEnd('/').ToLowerInvariant(); $r = $ResourceGroupId.TrimEnd('/').ToLowerInvariant()
|    ($s -eq $r) -or $s.StartsWith($r + '/')
|}
|
|function ConvertTo-SIDiagUtc {
|    <# PURE. A Log Analytics / ARM time (text) as UTC [datetime], or $null. #>
|    param([AllowNull()]$Value)
|    if ($null -eq $Value -or -not "$Value".Trim()) { return $null }
|    if ($Value -is [datetime]) { return $Value.ToUniversalTime() }
|    $d = [datetime]::MinValue
|    if ([datetime]::TryParse("$Value", [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]'AdjustToUniversal, AssumeUniversal', [ref]$d)) { return $d }
|    $null
|}
|
|# ---------------------------------------------------------------------------------------------------------------------
|# Seams and sign-in
|# ---------------------------------------------------------------------------------------------------------------------
|function Get-SIDiagnosticsDefaultSeams {
|    <# The real calls. Tests replace any of them. #>
|    @{
|        Arm     = { param([string]$Method, [string]$Path, [string]$ApiVersion, [switch]$List, $Body)
|                    $a = @{ Method = $(if ($Method) { $Method } else { 'GET' }); Path = $Path }
|                    if ($ApiVersion) { $a.ApiVersion = $ApiVersion }
|                    if ($null -ne $Body) { $a.Body = $Body }
|                    if ($List) { $a.List = $true }
|                    Invoke-SIArm @a }
|        LaQuery = { param([string]$WorkspaceId, [string]$Query) Invoke-SILaQuery -WorkspaceId $WorkspaceId -Query $Query }
|        Graph   = { param([string]$Query, [string[]]$Subscription) Search-SIResourceGraph -Query $Query -Subscription $Subscription }
|        Now     = { [datetime]::UtcNow }
|        # #239: the licence request state the updater keeps (Key Vault secret SI-LicenceRequest-State; never the token)
|        LicenceState = { param([string]$VaultName) Get-SIKeyVaultSecretValue -VaultName $VaultName -Name 'SI-LicenceRequest-State' }
|        # #240: the update state the updater keeps (source, last manifest per kind, holds; never the install key)
|        UpdateState  = { param([string]$VaultName) Get-SIKeyVaultSecretValue -VaultName $VaultName -Name 'SI-Update-State' }
|        Sleep   = { param([int]$Seconds) Start-Sleep -Seconds $Seconds }
|        Print   = { param([string]$Text, [string]$Color) if ($Color) { Write-Host $Text -ForegroundColor $Color } else { Write-Host $Text } }
|    }
|}
|
|function Merge-SIDiagnosticsSeams {
|    param([System.Collections.IDictionary]$Seams)
|    $s = Get-SIDiagnosticsDefaultSeams
|    if ($Seams) { foreach ($k in @($Seams.Keys)) { if ($Seams[$k] -is [scriptblock]) { $s[$k] = $Seams[$k] } } }
|    $s
|}
|
|function Initialize-SIDiagnosticsSignIn {
|    <#
|        Who the REST calls run as. SecurityInsight v3 uses no PowerShell modules, so there is no Az session to borrow:
|          Config     the install's own identity from its config: its managed identity on its VM / Arc server, or its
|                     service principal certificate (from the machine's certificate store)
|          Auto       a service principal certificate named in the environment (SI_DIAGNOSTICS_APPID +
|                     SI_DIAGNOSTICS_TENANTID + SI_DIAGNOSTICS_CERTTHUMBPRINT) when all three are set, otherwise Config
|          AzContext  no longer supported (it borrowed an Az PowerShell session); refused, naming the alternatives
|    #>
|    param([ValidateSet('Auto', 'AzContext', 'Config')][string]$SignIn = 'Auto', [System.Collections.IDictionary]$Values = @{})
|    $st = Get-SIAzRestState
|    if ($SignIn -eq 'AzContext') {
|        throw 'SecurityInsight no longer uses an Az PowerShell session (-SignIn AzContext). Use -SignIn Config (the install''s own identity), or set SI_DIAGNOSTICS_APPID, SI_DIAGNOSTICS_TENANTID and SI_DIAGNOSTICS_CERTTHUMBPRINT to a service principal whose certificate is in this machine''s certificate store.'
|    }
|    if ($SignIn -eq 'Auto') {
|        $eApp = [string]$env:SI_DIAGNOSTICS_APPID; $eTid = [string]$env:SI_DIAGNOSTICS_TENANTID; $eThumb = [string]$env:SI_DIAGNOSTICS_CERTTHUMBPRINT
|        if ($eApp -and $eTid -and $eThumb) {
|            $st.Connection = @{ Mode = 'Certificate'; AppId = $eApp; TenantId = $eTid; Thumbprint = ($eThumb -replace '\s', '') }
|            return 'Certificate'
|        }
|    }
|    $auth = [string]$Values['SI_AuthMethod']
|    if ($auth -eq 'ManagedIdentity' -or [bool]$Values['SI_UseManagedIdentity']) {
|        if (-not (Get-Command -Name Get-SIManagedIdentityToken -ErrorAction SilentlyContinue)) {
|            . ([IO.Path]::Combine($script:SIDiagRoot, 'auth', 'SI-ManagedIdentity.ps1'))
|            # published globally: the token layer looks it up after this function has returned
|            $f = Get-Command -Name Get-SIManagedIdentityToken -CommandType Function -ErrorAction SilentlyContinue
|            if ($f) { Set-Item -Path 'function:global:Get-SIManagedIdentityToken' -Value $f.ScriptBlock }
|        }
|        $cid = [string]$Values['SI_UAMI_ClientId']; if (-not $cid) { $cid = [string]$Values['SI_ManagedIdentityClientId'] }
|        $st.Connection = @{ Mode = 'ManagedIdentity'; ClientId = $cid }
|        return 'ManagedIdentity'
|    }
|    $app = [string]$Values['SI_SPN_AppId']; $tid = [string]$Values['SI_SPN_TenantId']; $thumb = [string]$Values['SI_SPN_CertThumbprint']
|    if ($app -and $tid -and $thumb) { $st.Connection = @{ Mode = 'Certificate'; AppId = $app; TenantId = $tid; Thumbprint = ($thumb -replace '\s', '') }; return 'Certificate' }
|    throw 'No sign-in: run this where the install''s own identity is available (its managed identity, or its service principal certificate in this machine''s certificate store), or set SI_DIAGNOSTICS_APPID, SI_DIAGNOSTICS_TENANTID and SI_DIAGNOSTICS_CERTTHUMBPRINT to a service principal that can read the install''s resource group and its workspace.'
|}
|
|# ---------------------------------------------------------------------------------------------------------------------
|# Test-SIInstall: data, run health, DCRs, isolation
|# ---------------------------------------------------------------------------------------------------------------------
|function Get-SIDiagLicenceRequest {
|    <# The licence request state (JSON from SI-LicenceRequest-State) as the client reads it; the client is loaded on first use. #>
|    param([AllowNull()][string]$Json)
|    if (-not (Get-Command -Name Get-SILicenceRequestStatus -ErrorAction SilentlyContinue)) {
|        . ([IO.Path]::Combine($script:SIDiagRoot, 'engine', '_shared', 'SI-LicenceRequest.ps1'))
|    }
|    Get-SILicenceRequestStatus -Json $Json
|}
|
|function Get-SIDiagUpdateState {
|    <#
|        #240: the update state (JSON from SI-Update-State) as the Pro update client reads it. $null on a copy without the
|        client (Community) -- that install takes no updates from Invardia.
|    #>
|    param([AllowNull()][string]$Json)
|    if (-not (Get-Command -Name Get-SIInvardiaUpdateStatus -ErrorAction SilentlyContinue)) {
|        $client = [IO.Path]::Combine($script:SIDiagRoot, 'engine', '_shared', 'SI-InvardiaUpdate.ps1')
|        if (-not (Test-Path -LiteralPath $client)) { return $null }
|        . $client
|    }
|    Get-SIInvardiaUpdateStatus -Json $Json
|}
|
|function New-SIDiagFinding {
|    param([Parameter(Mandatory)][string]$Area, [Parameter(Mandatory)][string]$Text)
|    [pscustomobject]@{ Area = $Area; Text = $Text }
|}
|
|function Get-SIRunHealthSummary {
|    <#
|        PURE. Run-health rows (Engine, Phase, At, ExitReason, DurationSec -- the latest per Engine + Phase) as one line per
|        engine: LastStart, LastEnd, ExitReason, DurationSec and Problem (empty = healthy). A problem is an END with a
|        failed ExitReason, or a START newer than the last END that is older than -RunningGraceHours (it never ended:
|        killed, out of memory, or stuck).
|    #>
|    param([AllowEmptyCollection()][object[]]$Rows = @(), [datetime]$NowUtc = [datetime]::UtcNow, [double]$RunningGraceHours = 4)
|    $by = [ordered]@{}
|    foreach ($r in @($Rows)) {
|        $e = [string]$r.Engine; if (-not $e) { continue }
|        if (-not $by.Contains($e)) { $by[$e] = [ordered]@{ Start = $null; End = $null; ExitReason = ''; DurationSec = '' } }
|        $at = ConvertTo-SIDiagUtc $r.At
|        if ([string]$r.Phase -eq 'Start') { $by[$e].Start = $at }
|        elseif ([string]$r.Phase -eq 'End') { $by[$e].End = $at; $by[$e].ExitReason = [string]$r.ExitReason; $by[$e].DurationSec = [string]$r.DurationSec }
|    }
|    foreach ($e in @($by.Keys | Sort-Object)) {
|        $h = $by[$e]; $problem = ''
|        if ($h.End -and ($script:SIDiagFailedExitReasons -contains $h.ExitReason)) { $problem = "its last run ended with '$($h.ExitReason)'" }
|        # #276: a dry run is not a failure, but nothing was published -- said, so a forgotten -WhatIfMode is seen.
|        if ($h.End -and $h.ExitReason -eq 'dry-run') { $problem = 'its last run was a dry run -- nothing was published' }
|        if ($h.Start -and (-not $h.End -or $h.Start -gt $h.End) -and ($NowUtc - $h.Start).TotalHours -gt $RunningGraceHours) {
|            $problem = 'its last run started {0:yyyy-MM-dd HH:mm}Z and never ended (stopped, out of memory, or still hanging)' -f $h.Start
|        }
|        [pscustomobject]@{ Engine = $e; LastStart = $h.Start; LastEnd = $h.End; ExitReason = $h.ExitReason; DurationSec = $h.DurationSec; Problem = $problem }
|    }
|}
|
|function Get-SIIdentityPrincipal {
|    <# The install's user-assigned identity: by name, else by client id, else the only one in its resource group. #>
|    param([Parameter(Mandatory)]$Target, [Parameter(Mandatory)][System.Collections.IDictionary]$Seams, [string]$IdentityName)
|    $list = @(& $Seams.Arm 'GET' ('{0}/providers/Microsoft.ManagedIdentity/userAssignedIdentities' -f $Target.ResourceGroupId) '2023-01-31' -List:$true $null | Where-Object { $_ })
|    $name = if ($IdentityName) { $IdentityName } else { $Target.IdentityName }
|    $pick = $null
|    if ($name) { $pick = @($list | Where-Object { [string]$_.name -eq $name }) | Select-Object -First 1 }
|    if (-not $pick -and $Target.IdentityClientId) { $pick = @($list | Where-Object { [string]$_.properties.clientId -eq $Target.IdentityClientId }) | Select-Object -First 1 }
|    if (-not $pick -and -not $name -and $list.Count -eq 1) { $pick = $list[0] }
|    if (-not $pick) { return $null }
|    [pscustomobject]@{ Name = [string]$pick.name; PrincipalId = [string]$pick.properties.principalId; ClientId = [string]$pick.properties.clientId }
|}
|
|function Get-SIPrincipalRoleAssignments {
|    <#
|        Every role assignment of a principal that this sign-in can see: ARM at the install's subscription (assignments at,
|        above and below it -- management groups included) plus Resource Graph (other subscriptions). Each:
|        @{ Id; Scope; RoleDefinitionId; Role }. Role names are resolved once per definition.
|    #>
|    param([Parameter(Mandatory)][string]$PrincipalId, [Parameter(Mandatory)][string]$SubscriptionId, [Parameter(Mandatory)][System.Collections.IDictionary]$Seams, $Notes)
|    $byId = [ordered]@{}
|    $filter = [uri]::EscapeDataString(("principalId eq '{0}'" -f $PrincipalId))
|    $arm = @(& $Seams.Arm 'GET' ("/subscriptions/{0}/providers/Microsoft.Authorization/roleAssignments?`$filter={1}" -f $SubscriptionId, $filter) '2022-04-01' -List:$true $null | Where-Object { $_ })
|    foreach ($a in $arm) { $byId[([string]$a.id).ToLowerInvariant()] = [pscustomobject]@{ Id = [string]$a.id; Scope = [string]$a.properties.scope; RoleDefinitionId = [string]$a.properties.roleDefinitionId } }
|    try {
|        $q = "authorizationresources | where type =~ 'microsoft.authorization/roleassignments' | where tostring(properties.principalId) =~ '{0}' | project id, scope = tostring(properties.scope), roleDefinitionId = tostring(properties.roleDefinitionId)" -f $PrincipalId
|        foreach ($g in @(& $Seams.Graph $q @() | Where-Object { $_ })) {
|            $k = ([string]$g.id).ToLowerInvariant()
|            if (-not $byId.Contains($k)) { $byId[$k] = [pscustomobject]@{ Id = [string]$g.id; Scope = [string]$g.scope; RoleDefinitionId = [string]$g.roleDefinitionId } }
|        }
|    } catch { if ($null -ne $Notes) { $Notes.Add(('Resource Graph could not be read, so only this subscription''s view of the role assignments was checked: {0}' -f $_.Exception.Message)) } }
|    $names = @{}
|    foreach ($a in $byId.Values) {
|        $rd = $a.RoleDefinitionId; $key = ($rd -split '/')[-1].ToLowerInvariant()
|        if (-not $names.ContainsKey($key)) {
|            $n = ''
|            try { $d = & $Seams.Arm 'GET' $rd '2022-04-01' -List:$false $null; $n = [string]$d.properties.roleName } catch { $n = '' }
|            $names[$key] = $(if ($n) { $n } else { "role $key" })
|        }
|        $a | Add-Member -NotePropertyName Role -NotePropertyValue $names[$key] -Force
|        $a
|    }
|}
|
|function Invoke-SIInstallCheck {
|    <#
|        The whole check. Returns @{ Ok; Findings; Notes; Tables; Engines; Dcrs; Identity; Assignments; Target }.
|        Findings = what is WRONG (exit 1). Notes = worth knowing, not wrong.
|    #>
|    param(
|        [Parameter(Mandatory)]$Target,
|        [Parameter(Mandatory)][System.Collections.IDictionary]$Seams,
|        [double]$SinceHours = 26,
|        [double]$RunningGraceHours = 4,
|        [string]$IdentityName,
|        [string]$PrincipalId,
|        [string[]]$AllowedGrant = @()
|    )
|    $say = { param($t, $c) try { & $Seams.Print $t $c } catch { } }
|    $findings = New-Object System.Collections.Generic.List[object]
|    $notes = New-Object System.Collections.Generic.List[string]
|    $now = & $Seams.Now
|    $res = [ordered]@{ Ok = $false; Findings = $null; Notes = $null; Tables = @(); Engines = @(); Dcrs = @(); Identity = $null; Assignments = @(); LicenceRequest = $null; Updates = $null; Target = $Target }
|    foreach ($req in 'SubscriptionId', 'ResourceGroup', 'WorkspaceResourceId') {
|        if (-not $Target.$req) { $findings.Add((New-SIDiagFinding -Area 'config' -Text "the config does not say $req")) }
|    }
|    if ($findings.Count) { $res.Findings = $findings.ToArray(); $res.Notes = $notes.ToArray(); return [pscustomobject]$res }
|    $h = [Math]::Max(1, [int][Math]::Ceiling($SinceHours))
|
|    & $say ("== SecurityInsight install: {0} / {1}" -f $Target.SubscriptionId, $Target.ResourceGroup) 'Cyan'
|
|    # ---- 1. data per SI table (Log Analytics data plane) ----
|    $wsGuid = ''
|    try { $w = & $Seams.Arm 'GET' $Target.WorkspaceResourceId '2022-10-01' -List:$false $null; $wsGuid = [string]$w.properties.customerId }
|    catch { $findings.Add((New-SIDiagFinding -Area 'workspace' -Text ("the workspace could not be read: {0}" -f $_.Exception.Message))) }
|    & $say ("== rows per SI table in the last {0} h" -f $h) 'Cyan'
|    if ($wsGuid) {
|        try {
|            # (LastSeen, not "last": that is a reserved word in KQL)
|            $q = "union withsource=SITable isfuzzy=true SI_* | where TimeGenerated > ago({0}h) | summarize Rows = count(), LastSeen = max(TimeGenerated) by SITable | order by SITable asc" -f $h
|            $rows = @((& $Seams.LaQuery $wsGuid $q).Results | Where-Object { $_ })
|            $res.Tables = @($rows | ForEach-Object { [pscustomobject]@{ Table = [string]$_.SITable; Rows = [long]$_.Rows; LastSeen = (ConvertTo-SIDiagUtc $_.LastSeen) } })
|            foreach ($t in $res.Tables) { & $say ('  {0,-40} {1,10}  last {2:yyyy-MM-dd HH:mm}Z' -f $t.Table, $t.Rows, $t.LastSeen) '' }
|            if (-not $res.Tables.Count) { $findings.Add((New-SIDiagFinding -Area 'data' -Text ("no SecurityInsight table received data in the last {0} h" -f $h))) }
|        } catch { $findings.Add((New-SIDiagFinding -Area 'data' -Text ("the SI tables could not be queried: {0}" -f $_.Exception.Message))) }
|
|        # ---- 2. run health per engine ----
|        & $say '== run health per engine (latest start / end)' 'Cyan'
|        try {
|            $q = "SI_RunHealth_CL | where TimeGenerated > ago({0}h) | extend ExitReason = tostring(column_ifexists('ExitReason', '')), DurationSec = tostring(column_ifexists('DurationSec', '')) | summarize arg_max(TimeGenerated, ExitReason, DurationSec) by Engine, Phase | project Engine, Phase, At = TimeGenerated, ExitReason, DurationSec | order by Engine asc, Phase asc" -f $h
|            $rh = @((& $Seams.LaQuery $wsGuid $q).Results | Where-Object { $_ })
|            $res.Engines = @(Get-SIRunHealthSummary -Rows $rh -NowUtc $now -RunningGraceHours $RunningGraceHours)
|            foreach ($e in $res.Engines) {
|                & $say ('  {0,-28} start {1,-17} end {2,-17} {3,-16} {4}' -f $e.Engine, $(if ($e.LastStart) { $e.LastStart.ToString('yyyy-MM-dd HH:mm') } else { '-' }),
|                    $(if ($e.LastEnd) { $e.LastEnd.ToString('yyyy-MM-dd HH:mm') } else { '-' }), $e.ExitReason, $(if ($e.DurationSec) { $e.DurationSec + ' s' } else { '' })) $(if ($e.Problem) { 'Red' } else { '' })
|                if ($e.Problem) { $findings.Add((New-SIDiagFinding -Area 'run health' -Text ('{0}: {1}' -f $e.Engine, $e.Problem))) }
|            }
|            if (-not $res.Engines.Count) { $findings.Add((New-SIDiagFinding -Area 'run health' -Text ("no engine reported a run in the last {0} h" -f $h))) }
|        } catch { $findings.Add((New-SIDiagFinding -Area 'run health' -Text ("the run-health table could not be read (no engine has reported yet?): {0}" -f $_.Exception.Message))) }
|    }
|
|    # ---- 3. the DCRs in its resource group(s) ----
|    & $say ("== data collection rules in {0}" -f $Target.ResourceGroup) 'Cyan'
|    $rgIds = @($Target.ResourceGroupId, $Target.DcrResourceGroupId | Where-Object { $_ } | ForEach-Object { $_.ToLowerInvariant() } | Select-Object -Unique)
|    $mine = New-Object System.Collections.Generic.List[object]
|    foreach ($rgId in $rgIds) {
|        try { foreach ($d in @(& $Seams.Arm 'GET' ($rgId + '/providers/Microsoft.Insights/dataCollectionRules') '2022-06-01' -List:$true $null | Where-Object { $_ })) { $mine.Add($d) } }
|        catch { $findings.Add((New-SIDiagFinding -Area 'dcr' -Text ("the data collection rules in {0} could not be listed: {1}" -f $rgId, $_.Exception.Message))) }
|    }
|    $res.Dcrs = @($mine | ForEach-Object { [pscustomobject]@{ Name = [string]$_.name; Id = [string]$_.id } } | Sort-Object Name)
|    foreach ($d in $res.Dcrs) { & $say ('  ' + $d.Name) '' }
|    $missingCfg = @($Target.DcrNames | Where-Object { $n = $_; -not @($res.Dcrs | Where-Object { $_.Name -eq $n }).Count })
|    if ($missingCfg.Count) { $notes.Add(('configured but not created yet (an engine creates its rule on its first run): {0}' -f ($missingCfg -join ', '))) }
|
|    # ---- 4. ISOLATION ----
|    & $say '== isolation: the install''s identity holds no write role outside its resource group' 'Cyan'
|    $pid_ = $PrincipalId
|    if (-not $pid_) {
|        try {
|            $ident = Get-SIIdentityPrincipal -Target $Target -Seams $Seams -IdentityName $IdentityName
|            if ($ident) { $res.Identity = $ident; $pid_ = $ident.PrincipalId }
|        } catch { $notes.Add(('the identities in the resource group could not be listed: {0}' -f $_.Exception.Message)) }
|    } else { $res.Identity = [pscustomobject]@{ Name = ''; PrincipalId = $PrincipalId; ClientId = '' } }
|    if (-not $pid_) {
|        $findings.Add((New-SIDiagFinding -Area 'isolation' -Text 'the install''s managed identity could not be found, so its access is UNKNOWN (not checked) -- pass -IdentityName or -PrincipalId'))
|    } else {
|        & $say ('  identity {0} ({1})' -f $res.Identity.Name, $pid_) ''
|        try {
|            $res.Assignments = @(Get-SIPrincipalRoleAssignments -PrincipalId $pid_ -SubscriptionId $Target.SubscriptionId -Seams $Seams -Notes $notes)
|            $doc = @(Get-SIInstallDocumentedWriteGrants -Target $Target) + @($AllowedGrant | Where-Object { $_ -match '@' } | ForEach-Object { $p = $_ -split '@', 2; [pscustomobject]@{ Role = $p[0].Trim(); Scope = $p[1].Trim() } })
|            foreach ($a in $res.Assignments) {
|                $inside = Test-SIScopeInside -Scope $a.Scope -ResourceGroupId $Target.ResourceGroupId
|                $write = $a.Role -match $script:SIDiagWriteRolePattern
|                $isDoc = @($doc | Where-Object { $_.Role -eq $a.Role -and $_.Scope.TrimEnd('/') -ieq $a.Scope.TrimEnd('/') }).Count -gt 0
|                $tag = if (-not $write) { 'read' } elseif ($inside) { 'inside' } elseif ($isDoc) { 'documented' } else { 'NOT ALLOWED' }
|                & $say ('  [{0,-11}] {1,-36} on {2}' -f $tag, $a.Role, $a.Scope) $(if ($tag -eq 'NOT ALLOWED') { 'Red' } else { '' })
|                if ($tag -eq 'NOT ALLOWED') { $findings.Add((New-SIDiagFinding -Area 'isolation' -Text ('{0} on {1} -- a write role outside the install''s resource group' -f $a.Role, $a.Scope))) }
|            }
|        } catch { $findings.Add((New-SIDiagFinding -Area 'isolation' -Text ('the identity''s role assignments could not be read, so its access is UNKNOWN: {0}' -f $_.Exception.Message))) }
|    }
|
|    & $say '== isolation: the install''s data collection rule names are unique in the subscription' 'Cyan'
|    try {
|        $all = @(& $Seams.Arm 'GET' ('/subscriptions/{0}/providers/Microsoft.Insights/dataCollectionRules' -f $Target.SubscriptionId) '2022-06-01' -List:$true $null | Where-Object { $_ })
|        $mineIds = @($res.Dcrs | ForEach-Object { $_.Id.ToLowerInvariant() })
|        $dups = 0
|        foreach ($d in $res.Dcrs) {
|            $others = @($all | Where-Object { [string]$_.name -ieq $d.Name -and $mineIds -notcontains ([string]$_.id).ToLowerInvariant() })
|            foreach ($o in $others) {
|                $dups++
|                $findings.Add((New-SIDiagFinding -Area 'isolation' -Text ('data collection rule name {0} is also used by {1} -- an engine that resolves the rule by name can send this install''s data there' -f $d.Name, [string]$o.id)))
|            }
|        }
|        & $say $(if ($dups) { "  $dups duplicate name(s)" } else { '  every name is unique' }) $(if ($dups) { 'Red' } else { '' })
|    } catch { $findings.Add((New-SIDiagFinding -Area 'isolation' -Text ('the subscription''s data collection rules could not be listed, so name uniqueness is UNKNOWN: {0}' -f $_.Exception.Message))) }
|
|    # ---- 5. the licence request (#239): requested / pending / approved / rejected, valid-to, the last check ----
|    $res.LicenceRequest = $null
|    if ($Target.KeyVaultName) {
|        & $say '== licence request' 'Cyan'
|        try {
|            $lr = Get-SIDiagLicenceRequest -Json (& $Seams.LicenceState $Target.KeyVaultName)
|            $res.LicenceRequest = $lr
|            & $say ('  {0}; last check {1}' -f $lr.Summary, $(if ($lr.LastCheckUtc) { ([datetime]$lr.LastCheckUtc).ToString('yyyy-MM-dd HH:mm') + 'Z' } else { 'never' })) $(if ($lr.Status -eq 'rejected') { 'Red' } elseif ($lr.LastError) { 'Yellow' } else { '' })
|            if ($lr.Status -eq 'rejected') { $findings.Add((New-SIDiagFinding -Area 'licence' -Text ('Invardia REJECTED this install''s licence request{0} -- contact Invardia, then run setup/Request-SILicense.ps1 -Force' -f $(if ($lr.Reason) { ": $($lr.Reason)" } else { '' })))) }
|            elseif ($lr.LastError) { $notes.Add(('licence request: ' + $lr.LastError)) }
|        } catch { $notes.Add(('the licence request state could not be read: {0}' -f $_.Exception.Message)) }
|    }
|
|    # ---- 6. updates (#240): the source, the last manifest per kind (version, sequence, ring), the last check, any HOLD ----
|    $res.Updates = $null
|    if ($Target.KeyVaultName -and $Seams.Contains('UpdateState')) {
|        try {
|            $json = & $Seams.UpdateState $Target.KeyVaultName
|            $us = Get-SIDiagUpdateState -Json $json
|            if ($us) {
|                & $say '== updates' 'Cyan'
|                $res.Updates = $us
|                & $say ('  {0}' -f $us.Summary) $(if ($us.Refused -or $us.ClaimResult -eq 'conflict') { 'Red' } elseif (@($us.Holds).Count -or $us.LastError) { 'Yellow' } else { '' })
|                foreach ($h in @($us.Holds)) { & $say ('  HOLD {0}' -f $h) 'Yellow'; $notes.Add(('update on hold -- {0}' -f $h)) }
|                if ($us.Refused) { $findings.Add((New-SIDiagFinding -Area 'updates' -Text ('an update manifest from Invardia was REFUSED: {0}' -f $us.LastError))) }
|                elseif ($us.ClaimResult -eq 'conflict') { $findings.Add((New-SIDiagFinding -Area 'updates' -Text ('the install key could not be claimed: {0}' -f $us.ClaimReason))) }
|                elseif ($us.LastError) { $notes.Add(('updates: ' + $us.LastError)) }
|            }
|        } catch { $notes.Add(('the update state could not be read: {0}' -f $_.Exception.Message)) }
|    }
|
|    $res.Findings = $findings.ToArray(); $res.Notes = $notes.ToArray(); $res.Ok = ($findings.Count -eq 0)
|    & $say '== summary' 'Cyan'
|    foreach ($n in $res.Notes) { & $say ('  note: ' + $n) 'DarkGray' }
|    if ($res.Ok) { & $say '  OK -- data arrives, every engine''s last run is healthy, and the install is isolated.' 'Green' }
|    else { foreach ($f in $res.Findings) { & $say ('  WRONG [{0}] {1}' -f $f.Area, $f.Text) 'Red' } }
|    [pscustomobject]$res
|}
|
|# ---------------------------------------------------------------------------------------------------------------------
|# Invoke-SIJobsOnce: every Container Apps job once, in schedule order
|# ---------------------------------------------------------------------------------------------------------------------
|function Get-SICronMinuteOfDay {
|    <# PURE. The minute of the day a cron expression fires first (minute hour ...); a field that is not a number counts as 0, an unreadable expression sorts last. #>
|    param([AllowNull()][string]$Cron)
|    $f = @("$Cron".Trim() -split '\s+')
|    if ($f.Count -lt 2) { return [int]::MaxValue }
|    $num = { param($x) $m = [regex]::Match("$x", '^\d+'); if ($m.Success) { [int]$m.Value } else { 0 } }
|    (& $num $f[1]) * 60 + (& $num $f[0])
|}
|
|function Get-SIJobRunPlan {
|    <#
|        PURE. The install's Container Apps jobs as run groups, in schedule order: jobs that start at the same time of day
|        form one group (they run in parallel), groups run one after the other. The updater (it changes the install) is
|        left out unless -IncludeUpdater; event-triggered jobs are left out (they run when work arrives). Returns
|        @{ Groups = @(@{ At; Jobs = @(@{ Name; Id; Cron }) }); Skipped = @(@{ Name; Why }) }.
|    #>
|    param([AllowEmptyCollection()][object[]]$Jobs = @(), [switch]$IncludeUpdater, [string[]]$Only = @(), [string[]]$Exclude = @())
|    $skipped = New-Object System.Collections.Generic.List[object]
|    $run = New-Object System.Collections.Generic.List[object]
|    foreach ($j in @($Jobs | Where-Object { $_ })) {
|        $name = [string]$j.name
|        $trigger = [string]$j.properties.configuration.triggerType
|        $cron = ''
|        try { $cron = [string]$j.properties.configuration.scheduleTriggerConfig.cronExpression } catch { $cron = '' }
|        if (@($Only).Count -and $Only -notcontains $name) { continue }
|        if ($Exclude -contains $name) { $skipped.Add([pscustomobject]@{ Name = $name; Why = 'excluded' }); continue }
|        if ($name -match '(?i)updater' -and -not $IncludeUpdater) { $skipped.Add([pscustomobject]@{ Name = $name; Why = 'the updater changes the install -- pass -IncludeUpdater to run it' }); continue }
|        if ($trigger -eq 'Event') { $skipped.Add([pscustomobject]@{ Name = $name; Why = 'event-triggered: it runs when work arrives' }); continue }
|        $run.Add([pscustomobject]@{ Name = $name; Id = [string]$j.id; Cron = $cron; Minute = $(if ($trigger -eq 'Schedule' -and $cron) { Get-SICronMinuteOfDay $cron } else { [int]::MaxValue - 1 }) })
|    }
|    $groups = @($run | Group-Object Minute | Sort-Object { [int]$_.Name } | ForEach-Object {
|        $m = [int]$_.Name
|        $at = if ($m -ge [int]::MaxValue - 1) { 'manual' } else { '{0:00}:{1:00}' -f [Math]::Floor($m / 60), ($m % 60) }
|        [pscustomobject]@{ At = $at; Jobs = @($_.Group | Sort-Object Name | ForEach-Object { [pscustomobject]@{ Name = $_.Name; Id = $_.Id; Cron = $_.Cron } }) }
|    })
|    [pscustomobject]@{ Groups = $groups; Skipped = $skipped.ToArray() }
|}
|
|function Invoke-SIJobRunOnce {
|    <#
|        Starts each group's jobs, waits for every execution to finish, then the next group. Returns
|        @{ Ok; Runs = @(@{ Job; Execution; Status; DurationMin; Group }) }. Success = every execution 'Succeeded'.
|    #>
|    param(
|        [Parameter(Mandatory)]$Plan,
|        [Parameter(Mandatory)][System.Collections.IDictionary]$Seams,
|        [int]$PollSeconds = 30,
|        [int]$TimeoutMinutes = 120
|    )
|    $say = { param($t, $c) try { & $Seams.Print $t $c } catch { } }
|    $runs = New-Object System.Collections.Generic.List[object]
|    $active = @('Running', 'Processing', 'Unknown', '')
|    $gi = 0
|    foreach ($g in @($Plan.Groups)) {
|        $gi++
|        & $say ('== group {0} ({1}): {2}' -f $gi, $g.At, (@($g.Jobs | ForEach-Object Name) -join ', ')) 'Cyan'
|        $live = @()
|        foreach ($j in @($g.Jobs)) {
|            $t0 = & $Seams.Now
|            try {
|                $r = & $Seams.Arm 'POST' ($j.Id + '/start') $script:SIDiagJobApi -List:$false $null
|                $exec = [string]$r.name
|                if (-not $exec -and $r.id) { $exec = ([string]$r.id -split '/')[-1] }
|                if (-not $exec) { throw 'the start returned no execution' }
|                & $say ('  {0:HH:mm:ss}  {1,-34} started {2}' -f $t0, $j.Name, $exec) ''
|                $live += [pscustomobject]@{ Job = $j.Name; Id = $j.Id; Execution = $exec; Start = $t0; Status = 'Running'; End = $null; Group = $gi }
|            } catch {
|                & $say ('  {0:HH:mm:ss}  {1,-34} could not be started: {2}' -f $t0, $j.Name, $_.Exception.Message) 'Red'
|                $runs.Add([pscustomobject]@{ Job = $j.Name; Execution = ''; Status = 'NotStarted'; DurationMin = 0; Group = $gi })
|            }
|        }
|        $deadline = (& $Seams.Now).AddMinutes($TimeoutMinutes)
|        while (@($live | Where-Object { $active -contains $_.Status }).Count) {
|            if ((& $Seams.Now) -ge $deadline) { break }
|            & $Seams.Sleep $PollSeconds
|            foreach ($x in @($live | Where-Object { $active -contains $_.Status })) {
|                try {
|                    $e = & $Seams.Arm 'GET' ('{0}/executions/{1}' -f $x.Id, $x.Execution) $script:SIDiagJobApi -List:$false $null
|                    $st = [string]$e.properties.status
|                    if ($st -and $active -notcontains $st) {
|                        $x.Status = $st
|                        $x.End = ConvertTo-SIDiagUtc $e.properties.endTime
|                        $s0 = ConvertTo-SIDiagUtc $e.properties.startTime; if ($s0) { $x.Start = $s0 }
|                        if (-not $x.End) { $x.End = & $Seams.Now }
|                        & $say ('  {0:HH:mm:ss}  {1,-34} {2,-10} after {3:N1} min' -f (& $Seams.Now), $x.Job, $st, ($x.End - $x.Start).TotalMinutes) $(if ($st -eq 'Succeeded') { 'Green' } else { 'Red' })
|                    }
|                } catch { & $say ('  {0,-34} status not readable yet: {1}' -f $x.Job, $_.Exception.Message) 'DarkGray' }
|            }
|        }
|        foreach ($x in $live) {
|            if ($active -contains $x.Status) {
|                $x.Status = 'TimedOut'; $x.End = & $Seams.Now
|                & $say ('  {0,-34} STILL RUNNING after {1} min -- counted as a failure' -f $x.Job, $TimeoutMinutes) 'Red'
|            }
|            $runs.Add([pscustomobject]@{ Job = $x.Job; Execution = $x.Execution; Status = $x.Status; DurationMin = [Math]::Round(($x.End - $x.Start).TotalMinutes, 1); Group = $x.Group })
|        }
|    }
|    $bad = @($runs | Where-Object { $_.Status -ne 'Succeeded' })
|    & $say '== summary' 'Cyan'
|    foreach ($r in $runs) { & $say ('  {0,-34} {1,-10} {2,6:N1} min  {3}' -f $r.Job, $r.Status, $r.DurationMin, $r.Execution) $(if ($r.Status -eq 'Succeeded') { '' } else { 'Red' }) }
|    & $say $(if ($bad.Count) { "  $($bad.Count) of $($runs.Count) job run(s) did not succeed." } else { "  all $($runs.Count) job run(s) succeeded." }) $(if ($bad.Count) { 'Red' } else { 'Green' })
|    [pscustomobject]@{ Ok = ($bad.Count -eq 0 -and $runs.Count -gt 0); Runs = $runs.ToArray() }
|}
'@ }
$__siSupportFiles['engine/_shared/SI-AzRest.ps1'] = @{ Sha256 = 'ab77e822fccc463f44911a2b47f52d56e82bdaac4b48f605f2252ecd332bfd5f'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- Azure over plain REST, without the Az.* PowerShell modules (REQUIREMENTS 9.3, decision 2:
|    "no PS module dependencies ... go pure REST").
|
|    SecurityInsight runs with NO PowerShell modules: every Azure call is plain REST with tokens from SecurityInsight's
|    own sign-in (managed identity, certificate client assertion, client secret -- the run's decision). There is no
|    switch and no module path: no Az module is loaded, installed or needed anywhere in the runtime.
|
|    The call sites keep the familiar names with 'SIAz' in place of 'Az' (Invoke-SIAzOperationalInsightsQuery,
|    Search-SIAzGraph, ...). Each wrapper takes the arguments the call sites pass and does the job over REST (its *Rest
|    twin), returning objects with the properties the call sites read. Connect-SIAzAccount only RECORDS which identity to
|    sign in as; each REST call mints its token when it needs one.
|    The REST building blocks are public and usable directly:
|        Get-SIAzureToken -Audience Arm|LaQuery|Storage|KeyVault|Graph      one token function per audience
|        Invoke-SILaQuery                                                   Log Analytics data plane (api.loganalytics.io)
|        Invoke-SIArm                                                       ARM GET/PUT/PATCH/DELETE, list with nextLink
|        Search-SIResourceGraph                                             Resource Graph, every page ($skipToken)
|        Get-SIKeyVaultSecretValue                                          one secret, as plain text
|        Get-SIBlobContent / Set-SIBlobContent / Get-SIBlobList / ...       blob data plane (OAuth, x-ms-version)
|        Send-SIQueueMessage / Receive-SIQueueMessage / Remove-SIQueueMessage
|        Get-SITableEntity / Set-SITableEntity                              table data plane (upsert)
|
|    HTTP: every call of this file goes through Invoke-SIAzRestHttp. Token requests (client secret) go through
|    SI-LogIngest.ps1's Invoke-SILogIngestHttp -- the same HttpWebRequest shape; tests mock both seams.
|    Token hook: $global:SI_TokenProvider = { param($Resource) ... } (a scriptblock returning a bearer token) is consulted
|    first by Get-SIAzureToken and Get-SILogIngestToken when set -- for a host with its own sign-in, e.g. setup.
|
|    Retry rule (CLAUDE.md working rule 4): 429 / 408 / 5xx / no response -> wait (Retry-After when sent) and retry
|    in-run; 401 once -> refresh the token and repeat once; any other 4xx -> FAIL FAST with the service's own body.
|
|    PS 5.1 safe (no ?. / ??, no RSA.ImportFromPem); works on pwsh 7 and in a Linux container (no Cert: drive needed).
|    Ships in both editions and never references a Pro path.
|#>
|
|# NO Set-StrictMode HERE -- a dot-sourced file that sets it leaks into the caller's scope.
|
|# #730: the streaming Log Analytics reader (Invoke-SILaQuery reads Risk Analysis' answers with it; compiled on first use)
|if (-not (Get-Command -Name Get-SILaStreamReaderType -ErrorAction Ignore)) {
|    $__siLaStream = [System.IO.Path]::Combine($PSScriptRoot, 'SI-LaStreamRead.ps1')
|    if ([System.IO.File]::Exists($__siLaStream)) { . $__siLaStream }
|}
|
|# ONE connect path (#524, owner 2026-10-09 "modern single connect only"): SecurityInsight's own REST token client --
|# managed identity, certificate, client secret (and, in setup, a person's own sign-in). The old sign-in mode "AzContext"
|# (#413: borrow the current Azure / Invardia Support session of the process) and its file SI-AzSession.ps1 are gone.
|#
|# ONE TOKEN SOURCE more for that same path (#524, owner 2026-10-09 via Invardia: "support installs use TOKENS, never the
|# secret"): in a shell where Invardia's Connect-InvardiaSupport is open, its function Get-InvardiaSupportToken -Resource <r>
|# returns a bearer token as the customer's Invardia support app (cached by Invardia, tid + appid verified there). SI takes
|# EVERY token from it -- Mode 'Support' -- and still checks each token's tenant against the tenant it works in. No session
|# state is read (only the token), no Az / Graph cmdlet is called. Outside a support session nothing changes.
|#
|# THE SESSION ITSELF IS USED (owner 2026-10-12: a change in an environment is made inside its Invardia Support session, so
|# it is recorded in that environment's audit log). Get-SISupportSession is the ONE place that says whether a session is
|# open: Invardia's $global:InvardiaSupportState names a tenant AND its recording command Invoke-InvardiaSupportRequest is
|# in the shell. With a session, who SecurityInsight works as (tenant, app, subscriptions) is read from it -- no sign-in of
|# SecurityInsight's own and no token request -- and every HTTP call goes through the recording command (Invoke-SISupportHttp).
|
|function Get-SISupportedSignInText {
|    <# PURE. The sign-ins SecurityInsight supports, for an error message. #>
|    'a managed identity (SI_AuthMethod = ManagedIdentity), an app with a certificate (SI_SPN_AppId + SI_SPN_TenantId + SI_SPN_CertThumbprint), an app with a client secret (SI_SPN_AppId + SI_SPN_TenantId + SI_SPN_Secret), or the tokens of an Invardia support session (Get-InvardiaSupportToken). An Azure session of this PowerShell process (Connect-AzAccount, az login) is never used'
|}
|
|function Get-SISupportSession {
|    <#
|        THE ONE PLACE that says whether an Invardia Support session is open in this PowerShell session, and what it names.
|        Open = Invardia's $global:InvardiaSupportState is a hashtable that names a tenant AND its recording command
|        Invoke-InvardiaSupportRequest is here (Test-Path Function: -- never Get-Command, which can load a module).
|        $null when there is none (Disconnect-InvardiaSupport empties the state). Never guessed: a state WITHOUT the
|        recording command is said and stops the caller -- nothing could be recorded.
|        Returns TenantId, AppId, Environment (the handle), EnvironmentId, SessionId, Subscriptions (lower case; the ones the
|        environment names), SubscriptionId (the first of them, '' when it names none), SubscriptionName.
|    #>
|    $s = Get-Variable -Scope Global -Name InvardiaSupportState -ValueOnly -ErrorAction Ignore
|    if (-not ($s -is [hashtable])) { return $null }
|    $tid = [string]$s['TenantId']
|    if ([string]::IsNullOrWhiteSpace($tid)) { return $null }
|    if (-not (Test-Path -LiteralPath 'Function:\Invoke-InvardiaSupportRequest')) {
|        throw ('An Invardia Support session is noted in this PowerShell session (tenant {0}), but its recording command Invoke-InvardiaSupportRequest is not here, so nothing SecurityInsight does could be recorded. Nothing was done. Open the session again (Connect-InvardiaSupport -Environment <handle> -Reason ''<why>''), or end it (Disconnect-InvardiaSupport) and work with your own sign-in.' -f $tid)
|    }
|    $subs = @(@($s['Subscriptions']) | Where-Object { $_ } | ForEach-Object { ([string]$_).Trim().ToLowerInvariant() } | Where-Object { $_ })
|    $first = ''
|    if ($subs.Count) { $first = [string]$subs[0] }
|    return [pscustomobject]@{
|        TenantId = $tid.Trim(); AppId = [string]$s['AppId']; Environment = [string]$s['Environment']; EnvironmentId = [string]$s['EnvironmentId']
|        SessionId = [string]$s['SessionId']; Subscriptions = [string[]]$subs; SubscriptionId = $first; SubscriptionName = [string]$s['SubscriptionName']
|    }
|}
|
|function Get-SISupportSessionName {
|    <# PURE. How a Support session is named in a message: its environment handle, else its tenant. #>
|    param($Session)
|    if ($Session -and [string]$Session.Environment) { return [string]$Session.Environment }
|    if ($Session) { return ('tenant {0}' -f $Session.TenantId) }
|    return ''
|}
|
|function Assert-SISupportSubscription {
|    <# In a Support session only a subscription the environment names is worked in: any other is REFUSED (throws). A session
|       whose environment names no subscription refuses none (Invardia's own rule). No session = nothing to check. #>
|    param([string]$SubscriptionId, $Session)
|    if ([string]::IsNullOrWhiteSpace($SubscriptionId)) { return }
|    if (-not $Session) { $Session = Get-SISupportSession }
|    if (-not $Session) { return }
|    $named = @($Session.Subscriptions)
|    if ($named.Count -and $named -notcontains $SubscriptionId.Trim().ToLowerInvariant()) {
|        throw ('Subscription {0} is not one the Invardia Support session for {1} names ({2}) -- refused, nothing was done there. Use a subscription of this environment, or open the Support session of the environment that owns {0}.' -f $SubscriptionId, (Get-SISupportSessionName $Session), ($named -join ', '))
|    }
|}
|
|function Test-SISupportTokenSource {
|    <# Is an Invardia Support session open in this shell? (Get-SISupportSession decides -- the one place.) #>
|    return [bool](Get-SISupportSession)
|}
|
|function Get-SISupportExpectedTenantId {
|    <# The tenant SI works in, which the Support session must be for: -TenantId, else the configured one. Empty = the
|       session's own. #>
|    param([string]$TenantId)
|    if ($TenantId) { return $TenantId }
|    return [string](Get-SIAzRestValue 'SI_SPN_TenantId', 'SpnTenantId', 'AzureTenantId', 'TenantId')
|}
|
|function Get-SISupportToken {
|    <#
|        A bearer token for -Resource from the Invardia Support session; its 'tid' must be -TenantId (refused otherwise).
|        ONLY for what has no HTTP request the recording command can send -- the SQL sign-in of a database step, the
|        container registry's own token exchange, reading who the Support app is from its token. Invardia records that the
|        token was issued; what is done with it is not recorded. Every HTTP call goes through Invoke-SISupportHttp instead
|        and asks for no token here.
|    #>
|    param([Parameter(Mandatory)][string]$Resource, [string]$TenantId, [switch]$ForceRefresh)
|    if (-not (Get-SISupportSession)) { throw 'No Invardia Support session is open in this PowerShell session (Connect-InvardiaSupport -Environment <handle> -Reason ''<why>'').' }
|    if (-not (Test-Path -LiteralPath 'Function:\Get-InvardiaSupportToken')) { throw ('The Invardia Support session in this PowerShell session has no token command (Get-InvardiaSupportToken), so no token for {0} can be taken from it. Open the session again (Connect-InvardiaSupport).' -f $Resource) }
|    $p = @{ Resource = $Resource.TrimEnd('/') }
|    if ($ForceRefresh) { $p['ForceRefresh'] = $true }
|    $tok = [string](Get-InvardiaSupportToken @p)
|    if ([string]::IsNullOrWhiteSpace($tok)) { throw ('The Invardia support session returned no token for {0}.' -f $Resource) }
|    $c = ConvertFrom-SIJwtPayload $tok
|    if (-not $c -or -not [string]$c.tid) { throw ('The Invardia support token for {0} could not be read (no tenant in it) -- refused.' -f $Resource) }
|    if ($TenantId -and [string]$c.tid -ne $TenantId) {
|        throw ('The Invardia support token for {0} is for tenant {1}, not {2} -- refused. Connect the support session of tenant {2}.' -f $Resource, $c.tid, $TenantId)
|    }
|    return $tok
|}
|
|function Get-SISupportAuth {
|    <# The Auth hashtable of the Invardia Support session: Mode 'Support', app + tenant + first subscription read from the
|       SESSION (Get-SISupportSession) -- no token is asked for. Refused when the session is for another tenant than
|       -TenantId / the configured one. ObjectId is not known here (Get-SISetupSignedInObjectId finds it when asked). #>
|    param([string]$TenantId)
|    $sess = Get-SISupportSession
|    if (-not $sess) { throw 'No Invardia Support session is open in this PowerShell session (Connect-InvardiaSupport -Environment <handle> -Reason ''<why>'').' }
|    $want = Get-SISupportExpectedTenantId -TenantId $TenantId
|    if ($want -and $want -ne $sess.TenantId) {
|        throw ('The Invardia Support session for {0} is for tenant {1}, not {2} -- refused. Connect the support session of tenant {2}.' -f (Get-SISupportSessionName $sess), $sess.TenantId, $want)
|    }
|    return @{ Mode = 'Support'; AppId = [string]$sess.AppId; TenantId = [string]$sess.TenantId; ObjectId = $null; SubscriptionId = [string]$sess.SubscriptionId
|              Environment = [string]$sess.Environment; EnvironmentId = [string]$sess.EnvironmentId; SessionId = [string]$sess.SessionId }
|}
|
|function Sync-SISupportConnection {
|    <#
|        Keeps the recorded sign-in of this process in step with the Invardia Support session, and returns the session
|        ($null = none):
|          * no session, but the recorded sign-in is a Support one  -> the session was closed: the sign-in is dropped
|          * a session and no recorded sign-in (or one of ANOTHER session) -> the session becomes the sign-in
|          * a session and a recorded sign-in of SecurityInsight's own -> kept, unless -TakeOver (setup: a Support session
|            in the shell always wins there -- setup never works beside it with a sign-in of its own)
|        Says ONE plain line the first time a session is used. Throws what Get-SISupportSession / Get-SISupportAuth refuse.
|    #>
|    param([switch]$TakeOver)
|    $sess = Get-SISupportSession
|    $st = Get-SIAzRestState
|    $c = $st.Connection
|    $isSupport = ($c -is [hashtable]) -and ([string]$c.Mode -eq 'Support')
|    if (-not $sess) {
|        if ($isSupport) { $st.Connection = $null; $st.TenantId = $null; $st.SubscriptionId = $null; $st.Cache = @{} }
|        return $null
|    }
|    $same = $isSupport -and ([string]$c.TenantId -eq $sess.TenantId) -and ([string]$c.SessionId -eq $sess.SessionId) -and ([string]$c.EnvironmentId -eq $sess.EnvironmentId)
|    if ($same) { return $sess }
|    if (($c -is [hashtable]) -and -not $isSupport -and -not $TakeOver) { return $sess }
|    $st.Connection = Get-SISupportAuth
|    $st.TenantId = [string]$sess.TenantId
|    $st.Cache = @{}
|    if ($st.SubscriptionId -and @($sess.Subscriptions).Count -and @($sess.Subscriptions) -notcontains ([string]$st.SubscriptionId).Trim().ToLowerInvariant()) { $st.SubscriptionId = $null }
|    $key = '{0}|{1}|{2}' -f $sess.TenantId, $sess.EnvironmentId, $sess.SessionId
|    if ([string]$st['SupportSaid'] -ne $key) {
|        $st['SupportSaid'] = $key
|        Write-Host ('using the Invardia Support session for {0} -- every change is recorded there' -f (Get-SISupportSessionName $sess))
|    }
|    return $sess
|}
|
|function Test-SISupportRecorderPresent {
|    <# #548: is an Invardia Support session, with its RECORDING wrapper, open in this shell? (Get-SISupportSession decides.) #>
|    return [bool](Get-SISupportSession)
|}
|
|function Test-SISupportRequestRoute {
|    <#
|        #548 (Invardia, 2026-10-10: every Support app action is recorded in the customer's audit log): does a request for
|        -Audience, as -Auth (none = the run's own sign-in), go through Invardia's recording wrapper? Yes when a Support
|        session is open (Get-SISupportSession) AND the call is made as the support session (Mode 'Support' -- the recorded
|        sign-in, or no recorded sign-in at all) AND no host token provider ($global:SI_TokenProvider) answers instead.
|        Every audience SecurityInsight signs in to: Arm, Graph, Log Analytics, Storage, Exchange Online's admin API, Key
|        Vault and Azure Monitor -- on any host (a host the wrapper does not know by itself gets its token audience named,
|        Get-SISupportTokenResource). A URL that is none of these (-Audience Other: another service with its own key) is
|        not a call as the support app and never goes through it. -Uri is accepted for callers that pass it.
|    #>
|    param([string]$Audience = 'Arm', [hashtable]$Auth, [string]$Uri)
|    if ($Audience -notin 'Arm', 'Graph', 'LaQuery', 'Storage', 'Exchange', 'KeyVault', 'Monitor') { return $false }
|    if ($Auth) {
|        if ([string]$Auth.Mode -ne 'Support') { return $false }
|        return [bool](Get-SISupportSession)
|    }
|    $tp = Get-Variable -Scope Global -Name SI_TokenProvider -ValueOnly -ErrorAction Ignore
|    if ($tp -is [scriptblock]) { return $false }
|    # a caller that loaded only part of this file (a script's own fakes, a lifted function) has no state helpers -- and no
|    # support session either
|    if (-not (Test-Path -LiteralPath 'Function:\Get-SIAzRestState')) { return $false }
|    if (-not (Test-Path -LiteralPath 'Function:\Sync-SISupportConnection')) { return $false }
|    if (-not (Sync-SISupportConnection)) { return $false }
|    $c = (Get-SIAzRestState).Connection
|    return (($c -is [hashtable]) -and ([string]$c.Mode -eq 'Support'))
|}
|
|function Get-SISupportTokenResource {
|    <# PURE. The token audience to NAME to the recording wrapper for a request it cannot name from the URL's host by
|       itself: a Key Vault or Azure Monitor URL on another host than <vault>.vault.azure.net /
|       <endpoint>.ingest.monitor.azure.com. '' = the wrapper names it (Arm, Graph, Log Analytics, Storage, Exchange). #>
|    param([string]$Audience, [string]$Uri)
|    $h = ''
|    try { $h = ([uri]$Uri).Host } catch { $h = '' }
|    if ($Audience -eq 'KeyVault' -and $h -notmatch '(?i)\.vault\.azure\.net$') { return 'https://vault.azure.net' }
|    if ($Audience -eq 'Monitor' -and $h -notmatch '(?i)\.ingest\.monitor\.azure\.com$') { return 'https://monitor.azure.com' }
|    return ''
|}
|
|function Test-SISupportReadOnlyPost {
|    <#
|        PURE. Is this POST a READ (recorded as a read, not as a change)? Only the POSTs known to change nothing:
|          ARM    Resource Graph (/providers/Microsoft.ResourceGraph/resources), a provider's checkNameAvailability, a
|                 workspace query (.../workspaces/<name>/query, /api/query)
|          Log Analytics   /v1/workspaces/<id>/query
|          Graph  getByIds, getMemberObjects, getMemberGroups, checkMemberObjects, checkMemberGroups, security/runHuntingQuery
|                 (a KQL hunting query), and a $batch whose
|                 requests are ALL GET
|        Anything else -- and anything not understood -- is a CHANGE. A GET / HEAD is a read by its method (not asked here).
|    #>
|    param([string]$Method, [string]$Uri, $Body)
|    if (([string]$Method).ToUpperInvariant() -ne 'POST') { return $false }
|    $u = $null
|    try { $u = [uri]$Uri } catch { return $false }
|    if (-not $u -or -not $u.IsAbsoluteUri) { return $false }
|    $h = $u.Host.ToLowerInvariant(); $p = $u.AbsolutePath
|    if ($h -match '^management\.(azure\.com|core\.windows\.net)$') {
|        if ($p -match '(?i)^/providers/Microsoft\.ResourceGraph/resources/?$') { return $true }
|        if ($p -match '(?i)/providers/[^/]+/checkNameAvailability/?$') { return $true }
|        if ($p -match '(?i)/providers/Microsoft\.OperationalInsights/workspaces/[^/]+/(api/)?query/?$') { return $true }
|        return $false
|    }
|    if ($h -eq 'api.loganalytics.io' -or $h -eq 'api.loganalytics.azure.com') { return [bool]($p -match '(?i)^/v1/workspaces/[^/]+/query/?$') }
|    if ($h -eq 'graph.microsoft.com') {
|        if ($p -match '(?i)/(getByIds|getMemberObjects|getMemberGroups|checkMemberObjects|checkMemberGroups)/?$') { return $true }
|        # Defender advanced hunting: a KQL query, which can only read
|        if ($p -match '(?i)^/(v1\.0|beta)/security/runHuntingQuery/?$') { return $true }
|        if ($p -match '(?i)^/(v1\.0|beta)/\$batch/?$') {
|            try {
|                $text = ''
|                if ($Body -is [byte[]]) { $text = [System.Text.Encoding]::UTF8.GetString($Body) } else { $text = [string]$Body }
|                $reqs = @(($text | ConvertFrom-Json).requests | Where-Object { $null -ne $_ })
|                if (-not $reqs.Count) { return $false }
|                return (-not @($reqs | Where-Object { ([string]$_.method).ToUpperInvariant() -ne 'GET' }).Count)
|            } catch { return $false }
|        }
|        return $false
|    }
|    return $false
|}
|
|function Test-SISupportBodyIsText {
|    <# PURE. Can -Body go through Invardia's recording wrapper? Yes for every body: the wrapper sends a [byte[]] body
|       unchanged (Invardia, 2026-10-10). Kept as the one place to say otherwise. #>
|    param($Body, [string]$ContentType)
|    return $true
|}
|
|function Invoke-SISupportHttp {
|    <#
|        #548: ONE HTTP exchange through Invardia's recording wrapper, in the shape of Invoke-SIAzRestHttp (StatusCode,
|        Content, Bytes, Headers, RetryAfter) so Invoke-SIAzRestRequest's retry and error rules stay exactly as they are
|        (an HTTP status >= 400 becomes SecurityInsight's own error there). The wrapper adds the support app's token: an
|        Authorization header of the caller is dropped. No answer = StatusCode 0 (retried like any network failure); a
|        refusal to record the action in the customer's audit log is RETHROWN (fail-closed: the action was not made).
|        A GET / HEAD is a read by its method; a POST that only reads (Test-SISupportReadOnlyPost) is sent -ReadOnly;
|        everything else is recorded as a change. An Azure Resource Manager URL of a subscription the session's environment
|        does not name is REFUSED before anything is sent (Assert-SISupportSubscription). -Audience names the token audience
|        for a host the wrapper does not know (Get-SISupportTokenResource); -TimeoutSec is passed on.
|    #>
|    param([Parameter(Mandatory)][string]$Method, [Parameter(Mandatory)][string]$Uri, [hashtable]$Headers, $Body, [string]$ContentType, [switch]$AsBytes,
|          [string]$Audience, [int]$TimeoutSec = 0)
|    $sess = Get-SISupportSession
|    if (-not $sess) { throw 'No Invardia support session is open in this PowerShell session, so this request cannot be sent through it.' }
|    $target = $null
|    try { $target = [uri]$Uri } catch { $target = $null }
|    if ($target -and $target.IsAbsoluteUri -and $target.Host -match '(?i)^management\.(azure\.com|core\.windows\.net)$' -and
|        $target.AbsolutePath -match '(?i)^/subscriptions/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(/|$)') {
|        Assert-SISupportSubscription -SubscriptionId $Matches[1] -Session $sess
|    }
|    $h = @{}
|    if ($Headers) { foreach ($k in @($Headers.Keys)) { if ([string]$k -ine 'Authorization' -and [string]$k -ine 'Content-Type') { $h[[string]$k] = $Headers[$k] } elseif ([string]$k -ieq 'Content-Type' -and -not $ContentType) { $ContentType = [string]$Headers[$k] } } }
|    $p = @{ Method = $Method.ToUpperInvariant(); Uri = $Uri }
|    if ($h.Count) { $p.Headers = $h }
|    if ($null -ne $Body) {
|        # bytes go unchanged (a source package upload). NOT $(if ...): a subexpression ENUMERATES the byte array into an
|        # object[] -- the wrapper then sent it as JSON numbers instead of the file
|        if ($Body -is [byte[]]) { $p.Body = $Body } else { $p.Body = [string]$Body }
|        if ($ContentType) { $p.ContentType = $ContentType }
|    }
|    $o = $null
|    if ($AsBytes) { $p.AsBytes = $true }   # the raw answer as ContentBytes (a download)
|    if (Test-SISupportReadOnlyPost -Method $Method -Uri $Uri -Body $Body) { $p.ReadOnly = $true }   # a POST that only reads
|    if ($TimeoutSec -gt 0) { $p.TimeoutSec = $TimeoutSec }
|    $tokenResource = Get-SISupportTokenResource -Audience $Audience -Uri $Uri
|    if ($tokenResource) { $p.TokenResource = $tokenResource }
|    try { $o = Invoke-InvardiaSupportRequest @p }
|    catch {
|        $m = [string]$_.Exception.Message
|        if ($m -match '(?i)audit log|fail-closed|could not be recorded|No Invardia support session') { throw }
|        return [pscustomobject]@{ StatusCode = 0; Content = $m; Bytes = $null; Headers = @{}; RetryAfter = $null }
|    }
|    $hh = New-Object 'System.Collections.Hashtable' ([System.StringComparer]::OrdinalIgnoreCase)
|    if ($o -and $o.Headers) {
|        try {
|            if ($o.Headers -is [System.Collections.IDictionary]) { foreach ($k in @($o.Headers.Keys)) { $hh[[string]$k] = (@($o.Headers[$k]) | ForEach-Object { [string]$_ }) -join ',' } }
|            else { foreach ($k in @($o.Headers.AllKeys)) { $hh[[string]$k] = [string]$o.Headers[$k] } }
|        } catch { }
|    }
|    $text = if ($o) { [string]$o.Content } else { '' }
|    # the raw answer as [byte[]] -- assigned in statements, never through $( ... ), which would enumerate it into object[]
|    [byte[]]$raw = $null
|    if ($AsBytes) {
|        if ($o -and $o.PSObject.Properties['ContentBytes'] -and $o.ContentBytes) { $raw = [byte[]]$o.ContentBytes } else { $raw = [System.Text.Encoding]::UTF8.GetBytes($text) }
|    }
|    $out = [pscustomobject]@{
|        StatusCode = $(if ($o) { [int]$o.StatusCode } else { 0 }); Content = $(if ($AsBytes) { '' } else { $text })
|        Bytes = $null; Headers = $hh; RetryAfter = [string]$hh['Retry-After']
|    }
|    $out.Bytes = $raw
|    $out
|}
|
|function Invoke-SIRestMethod {
|    <#
|        #548: the drop-in for Invoke-RestMethod that setup's own Graph / ARM calls use (-Method, -Uri, -Headers with the
|        caller's bearer token, -Body, -ContentType): inside an Invardia support session the call goes through the recording
|        wrapper (the caller's Authorization header is dropped -- the wrapper signs as the support app); otherwise exactly
|        Invoke-RestMethod. Throws on HTTP >= 400 like Invoke-RestMethod, with the service's answer in the message; returns
|        the parsed JSON (or the text when it is not JSON).
|    #>
|    [CmdletBinding()]   # -ErrorAction and the other common parameters, as Invoke-RestMethod callers pass them
|    param([string]$Method = 'GET', [Parameter(Mandatory)][string]$Uri, [hashtable]$Headers, $Body, [string]$ContentType, [int]$TimeoutSec = 120)
|    $host_ = ([uri]$Uri).Host
|    $aud = if ($host_ -eq 'graph.microsoft.com') { 'Graph' } elseif ($host_ -match '^management\.(azure\.com|core\.windows\.net)$') { 'Arm' } elseif ($host_ -eq 'api.loganalytics.io') { 'LaQuery' } elseif ($host_ -eq 'outlook.office365.com') { 'Exchange' } else { 'Other' }
|    # this function is published GLOBALLY: a caller that never loaded this file (a script run on its own, a test with its
|    # own fakes) has no routing helpers -- and then no support session either: plain Invoke-RestMethod
|    if ((Test-Path -LiteralPath 'Function:\Test-SISupportRequestRoute') -and (Test-SISupportRequestRoute -Audience $aud)) {
|        $b = $Body
|        if ($null -ne $b -and -not ($b -is [string]) -and -not ($b -is [byte[]])) { $b = ConvertTo-Json -InputObject $b -Depth 30 -Compress }
|        $ct = if ($ContentType) { $ContentType } elseif ($null -ne $b) { 'application/json' } else { '' }
|        $r = Invoke-SISupportHttp -Method $Method -Uri $Uri -Headers $Headers -Body $b -ContentType $ct -Audience $aud -TimeoutSec $TimeoutSec
|        $code = [int]$r.StatusCode
|        if ($code -lt 200 -or $code -ge 300) {
|            throw (New-SIAzRestError -Message ('{0} {1} failed. HTTP Status: {2} ({3}) Response: {4}' -f $Method.ToUpperInvariant(), ($Uri -replace '\?.*$', ''), $code, (Get-SIAzRestStatusName $code), $r.Content) -Response $r)
|        }
|        $t = [string]$r.Content
|        if (-not $t.Trim()) { return $null }
|        try { return ($t | ConvertFrom-Json) } catch { return $t }
|    }
|    $a = @{ Method = $Method; Uri = $Uri; ErrorAction = 'Stop'; TimeoutSec = $TimeoutSec }
|    if ($Headers) { $a.Headers = $Headers }
|    if ($null -ne $Body) { $a.Body = $Body }
|    if ($ContentType) { $a.ContentType = $ContentType }
|    Invoke-RestMethod @a
|}
|# published globally: a product script the install runs (in this process) finds it even when it loaded only part of the layer
|Set-Item -Path 'function:global:Invoke-SIRestMethod' -Value ${function:Invoke-SIRestMethod}
|
|# =====================================================================================================================
|#  The wrapper map, shared state
|# =====================================================================================================================
|
|function Get-SIAzRestWrapperMap {
|    <# wrapper -> the Az cmdlet it replaces -> its REST twin, as data. The wiring tests read it. #>
|    $m = [ordered]@{}
|    foreach ($az in @(
|        'Connect-AzAccount', 'Disconnect-AzAccount', 'Disable-AzContextAutosave', 'Get-AzContext', 'Set-AzContext',
|        'Get-AzAccessToken', 'Get-AzSubscription', 'Invoke-AzRestMethod',
|        'Invoke-AzOperationalInsightsQuery', 'Get-AzOperationalInsightsWorkspace', 'New-AzOperationalInsightsWorkspace',
|        'Search-AzGraph', 'Get-AzKeyVaultSecret', 'Set-AzKeyVaultSecret',
|        'Get-AzResourceGroup', 'New-AzResourceGroup', 'Get-AzRoleAssignment', 'New-AzRoleAssignment', 'Get-AzRoleDefinition',
|        'Get-AzTag', 'Update-AzTag', 'Get-AzADServicePrincipal',
|        'Get-AzDataCollectionEndpoint', 'New-AzDataCollectionEndpoint', 'Get-AzDataCollectionRule',
|        'New-AzStorageContext', 'Get-AzStorageAccount', 'New-AzStorageAccount',
|        'Get-AzStorageContainer', 'New-AzStorageContainer', 'Get-AzStorageBlob', 'Get-AzStorageBlobContent',
|        'Set-AzStorageBlobContent', 'Remove-AzStorageBlob', 'Start-AzStorageBlobCopy',
|        'Get-AzStorageQueue', 'New-AzStorageQueue')) {
|        $w = $az -replace '-Az', '-SIAz'
|        $m[$w] = @{ Replaces = $az; Rest = ($w + 'Rest') }
|    }
|    return $m
|}
|
|function Get-SIAzRestState {
|    <# Per-process state: the recorded sign-in, the current subscription, token / lookup caches. Global because this
|       file is dot-sourced at different depths by different engines. #>
|    # StrictMode-safe: an unset global is read through Get-Variable, never directly (a caller may run Set-StrictMode).
|    if (-not ((Get-Variable -Scope Global -Name SI_AzRestState -ValueOnly -ErrorAction Ignore) -is [hashtable])) {
|        $global:SI_AzRestState = @{ Connection = $null; SubscriptionId = $null; TenantId = $null; Cache = @{} }
|    }
|    return $global:SI_AzRestState
|}
|
|function Initialize-SIAzRestHelpers {
|    <# The token functions (SI-LogIngest.ps1), the KQL error reader (SI-KqlError.ps1) and the certificate helpers
|       (auth/Find-SICertificate.ps1). Loaded on first need; only what is MISSING is loaded and published globally, so a
|       caller's own copy or a test's mock is never replaced. #>
|    $want = @(
|        @{ Path = (Join-Path $PSScriptRoot 'SI-LogIngest.ps1'); Fns = @('Get-SILogIngestToken', 'Invoke-SILogIngestHttp', 'Get-SILogIngestRunCache', 'Get-SILogIngestRetryDelay', 'Initialize-SILogIngestAuthHelpers') }
|        @{ Path = (Join-Path $PSScriptRoot 'SI-KqlError.ps1');   Fns = @('Get-SIKqlErrorText', 'Get-SIKqlErrorSummary', 'Test-SIKqlTableMissing') }
|        @{ Path = (Join-Path (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)) 'auth/Find-SICertificate.ps1'); Fns = @('Get-SICertificateClientToken', 'Get-SICertificateFromStore', 'Test-SICertDriveAvailable') }
|    )
|    foreach ($w in $want) {
|        $missing = @($w.Fns | Where-Object { -not (Get-Command -Name $_ -ErrorAction Ignore) })
|        if ($missing.Count -eq 0) { continue }
|        if (-not (Test-Path -LiteralPath $w.Path)) { continue }
|        . $w.Path
|        foreach ($n in $missing) {
|            $f = Get-Command -Name $n -CommandType Function -ErrorAction Ignore
|            if ($f) { Set-Item -Path ("function:global:{0}" -f $n) -Value $f.ScriptBlock }
|        }
|    }
|}
|
|# =====================================================================================================================
|#  HTTP seam, sign-in, tokens
|# =====================================================================================================================
|
|function Remove-SIAzRestCaughtError {
|    <# Takes a HANDLED error record back out of $global:Error (newest entries only). PS 5.1 safe. #>
|    param($Record)
|    if ($null -eq $Record) { return }
|    $errs = $global:Error
|    for ($i = 0; $i -lt [Math]::Min(3, $errs.Count); $i++) {
|        $e = $errs[$i]
|        if ([object]::ReferenceEquals($e, $Record) -or ($e -is [System.Management.Automation.ErrorRecord] -and $Record -is [System.Management.Automation.ErrorRecord] -and [object]::ReferenceEquals($e.Exception, $Record.Exception))) {
|            $errs.RemoveAt($i); return
|        }
|    }
|}
|
|function Invoke-SIAzRestHttp {
|    <#
|        THE ONE HTTP SEAM of this file (tests Mock it). Never throws on an HTTP status: returns
|        @{ StatusCode; Content; Bytes; Headers; RetryAfter }. A network failure (no response) is StatusCode 0.
|        HttpWebRequest, not Invoke-WebRequest: the 4xx body and headers read the same way on PS 5.1 and pwsh 7.
|        -AsBytes keeps the body as bytes (blob downloads); Content is then ''.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$Method,
|        [Parameter(Mandatory)][string]$Uri,
|        [hashtable]$Headers,
|        $Body,
|        [string]$ContentType,
|        [int]$TimeoutSec = 300,
|        [switch]$AsBytes,
|        # A 2xx body read AS IT ARRIVES (SI-LaStreamRead.ps1): { param([IO.Stream]$Stream) <the parsed answer> } -- the body
|        # is never held whole; the answer is returned as .Parsed (Content '', Bytes $null). Any other status: as without it.
|        [scriptblock]$ReadStream
|    )
|    if ($PSVersionTable.PSEdition -ne 'Core') {
|        [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
|    }
|    $req = [System.Net.HttpWebRequest]::Create($Uri)
|    $req.Method = $Method.ToUpperInvariant()
|    $req.Timeout = $TimeoutSec * 1000
|    $req.ReadWriteTimeout = $TimeoutSec * 1000
|    $req.Accept = 'application/json'
|    if ($Headers) {
|        foreach ($k in $Headers.Keys) {
|            if ($k -eq 'Content-Type') { $req.ContentType = [string]$Headers[$k] }
|            elseif ($k -eq 'Accept')   { $req.Accept = [string]$Headers[$k] }
|            else { $req.Headers[$k] = [string]$Headers[$k] }
|        }
|    }
|    if ($ContentType) { $req.ContentType = $ContentType }
|    if ($null -ne $Body) {
|        # statements, never `= if (...) { $Body }`: an if-expression ENUMERATES a byte array into object[] (one boxed object
|        # per byte) -- a build context of tens of MB became gigabytes and the updater ran out of memory
|        [byte[]]$bytes = $null
|        if ($Body -is [byte[]]) { $bytes = $Body } else { $bytes = [System.Text.Encoding]::UTF8.GetBytes([string]$Body) }
|        $req.ContentLength = $bytes.Length
|        # A connection that fails while the BODY is sent (connect, DNS, reset) is "no answer" (StatusCode 0), which the caller
|        # retries -- for a request that is safe to send again (PUT / PATCH / DELETE / MERGE: idempotent, as an ARM or table PUT
|        # is). A POST that failed here is thrown as before: it is not repeated blindly. (The sweep of 2026-10-22: this threw
|        # past every retry loop on blob, table and ARM writes.)
|        try {
|            $s = $req.GetRequestStream()
|            try { $s.Write($bytes, 0, $bytes.Length) } finally { $s.Close() }
|        } catch {
|            if ($req.Method -eq 'POST') { throw }
|            return [pscustomobject]@{ StatusCode = 0; Content = [string]$_.Exception.Message; Bytes = $null; Headers = @{}; RetryAfter = $null }
|        }
|    } elseif ($req.Method -in 'POST', 'PUT', 'PATCH', 'MERGE') {
|        $req.ContentLength = 0
|    }
|    $resp = $null
|    try { $resp = $req.GetResponse() }
|    catch {
|        $we = $_.Exception
|        while ($we -and -not ($we -is [System.Net.WebException])) { $we = $we.InnerException }
|        if ($we -and $we.Response) {
|            $resp = $we.Response
|            # An HTTP status is an ANSWER, returned to the caller (who decides whether a 404 is "not there" or a failure)
|            # -- not an error of this process. PowerShell still records the caught exception in $Error, and setup shows
|            # every new $Error entry: each "does it exist?" probe printed "(404) Not Found" (live 2026-10-06). Drop it.
|            Remove-SIAzRestCaughtError -Record $_
|        }
|        else { return [pscustomobject]@{ StatusCode = 0; Content = [string]$_.Exception.Message; Bytes = $null; Headers = @{}; RetryAfter = $null } }
|    }
|    try {
|        $h = New-Object 'System.Collections.Hashtable' ([System.StringComparer]::OrdinalIgnoreCase)
|        foreach ($k in $resp.Headers.AllKeys) { $h[$k] = [string]$resp.Headers[$k] }
|        $text = ''; $raw = $null
|        $rs = $resp.GetResponseStream()
|        $sc = [int]$resp.StatusCode
|        if ($rs -and $ReadStream -and $sc -ge 200 -and $sc -lt 300) {
|            $parsed = $null
|            try { $parsed = & $ReadStream $rs } finally { $rs.Close() }
|            return [pscustomobject]@{ StatusCode = $sc; Content = ''; Bytes = $null; Headers = $h; RetryAfter = [string]$h['Retry-After']; Parsed = $parsed }
|        }
|        if ($rs) {
|            # #639: the body is read ONCE into an array of its own length when the service says how long it is -- not into a
|            # growing buffer that is then copied again (a large answer was held two or three times before it was parsed)
|            try {
|                $len = [long]$resp.ContentLength
|                if ($len -gt 0 -and $len -lt [int]::MaxValue) {
|                    $raw = [byte[]]::new([int]$len); $off = 0
|                    while ($off -lt $len) { $n = $rs.Read($raw, $off, [int]($len - $off)); if ($n -le 0) { break }; $off += $n }
|                    if ($off -lt $len) { $part = [byte[]]::new($off); [Array]::Copy($raw, $part, $off); $raw = $part; $part = $null }
|                } else {
|                    $ms = New-Object System.IO.MemoryStream
|                    $rs.CopyTo($ms); $raw = $ms.ToArray(); $ms.Dispose(); $ms = $null
|                }
|            } finally { $rs.Close() }
|            if (-not $AsBytes) { $text = [System.Text.Encoding]::UTF8.GetString($raw); $raw = $null }
|        }
|        return [pscustomobject]@{ StatusCode = [int]$resp.StatusCode; Content = $text; Bytes = $raw; Headers = $h; RetryAfter = [string]$h['Retry-After'] }
|    } finally { $resp.Close() }
|}
|
|function Get-SIAzRestValue {
|    <# The first non-empty global of -Names. #>
|    param([string[]]$Names)
|    foreach ($n in $Names) {
|        $v = Get-Variable -Scope Global -Name $n -ValueOnly -ErrorAction Ignore
|        if ($null -ne $v -and -not [string]::IsNullOrWhiteSpace([string]$v)) { return [string]$v }
|    }
|    return $null
|}
|
|function Resolve-SIAzRestAuth {
|    <#
|        WHO this run signs in as, for the REST path:
|          1. what Connect-SIAzAccount recorded in this process (the launcher / container entry point decided)
|          1b. an Invardia Support session open in this shell (Mode 'Support', read from the session)
|          2. the run's managed-identity switch (SI_UseManagedIdentity / UseManagedIdentity, #222)
|          3. an SPN certificate   (SI_SPN_AppId | SpnClientId | HighPriv_* + SI_SPN_CertThumbprint | SpnCertificateThumbprint)
|          4. an SPN client secret (SI_SPN_Secret | SpnClientSecret | HighPriv_*)
|        Certificate before secret, as everywhere in SecurityInsight. Returns the Auth hashtable Get-SILogIngestToken
|        takes. Throws when nothing is configured -- the REST path never falls back to an Az session.
|    #>
|    # An Invardia Support session in this shell: it IS the sign-in when nothing else was recorded (and a Support sign-in
|    # whose session was closed is dropped) -- Sync-SISupportConnection, read from the session, no token asked for.
|    $null = Sync-SISupportConnection
|    $st = Get-SIAzRestState
|    if ($st.Connection -is [hashtable]) { return $st.Connection }
|    # #524: the retired sign-in mode "AzContext" (borrow this process's Azure session) is refused by name
|    if ([string](Get-Variable -Scope Global -Name SI_AuthMethod -ValueOnly -ErrorAction Ignore) -eq 'AzContext') {
|        throw ('SI_AuthMethod = AzContext (use the current Azure session of this PowerShell process) is no longer supported: SecurityInsight signs in itself. Supported sign-ins: {0}.' -f (Get-SISupportedSignInText))
|    }
|    if ([bool](Get-Variable -Scope Global -Name SI_UseManagedIdentity -ValueOnly -ErrorAction Ignore) -or [bool](Get-Variable -Scope Global -Name UseManagedIdentity -ValueOnly -ErrorAction Ignore)) {
|        return @{ Mode = 'ManagedIdentity'; ClientId = [string](Get-SIAzRestValue 'SI_UAMI_ClientId', 'SI_ManagedIdentityClientId') }
|    }
|    $tid   = Get-SIAzRestValue 'SI_SPN_TenantId', 'SpnTenantId', 'HighPriv_Modern_TenantID', 'AzureTenantId', 'TenantId'
|    $app   = Get-SIAzRestValue 'SI_SPN_AppId', 'SpnClientId', 'HighPriv_Modern_ApplicationID_Azure'
|    $thumb = Get-SIAzRestValue 'SI_SPN_CertThumbprint', 'SpnCertificateThumbprint', 'HighPriv_Modern_CertificateThumbprint_Azure'
|    $sec   = Get-SIAzRestValue 'SI_SPN_Secret', 'SpnClientSecret', 'HighPriv_Modern_Secret_Azure', 'HighPriv_Modern_ApplicationSecret_Azure'
|    if ($app -and $thumb -and $tid) { return @{ Mode = 'Certificate'; AppId = $app; TenantId = $tid; Thumbprint = ($thumb -replace '\s', '') } }
|    if ($app -and $sec -and $tid)   { return @{ Mode = 'Secret'; AppId = $app; TenantId = $tid; Secret = $sec } }
|    throw ('No sign-in is configured for Azure access over REST. Supported sign-ins: {0}.' -f (Get-SISupportedSignInText))
|}
|
|function Get-SIAzureAudience {
|    <# The token resource of each audience the REST path talks to. #>
|    param([Parameter(Mandatory)][ValidateSet('Arm', 'LaQuery', 'Storage', 'KeyVault', 'Graph', 'Monitor')][string]$Audience)
|    switch ($Audience) {
|        'Arm'      { 'https://management.azure.com/' }
|        'LaQuery'  { 'https://api.loganalytics.io/' }
|        'Storage'  { 'https://storage.azure.com/' }
|        'KeyVault' { 'https://vault.azure.net/' }
|        'Graph'    { 'https://graph.microsoft.com/' }
|        'Monitor'  { 'https://monitor.azure.com/' }
|    }
|}
|
|function Get-SIAzureToken {
|    <#
|        ONE token function for every audience: a bearer token as the identity Resolve-SIAzRestAuth names, minted by
|        Get-SILogIngestToken (managed identity endpoint / certificate client assertion / client secret), cached per
|        identity + audience until 5 minutes before expiry. -Audience or a raw -Resource; -Auth overrides the identity.
|    #>
|    param(
|        [ValidateSet('Arm', 'LaQuery', 'Storage', 'KeyVault', 'Graph', 'Monitor')][string]$Audience = 'Arm',
|        [string]$Resource,
|        [hashtable]$Auth,
|        [switch]$ForceRefresh
|    )
|    if (-not $Resource) { $Resource = Get-SIAzureAudience -Audience $Audience }
|    # A host that signs in its own way (setup, a test) can supply tokens: $global:SI_TokenProvider = { param($Resource) <token> }.
|    # Consulted first, only when no explicit -Auth was passed; an empty answer falls through to SecurityInsight's own sign-in.
|    if (-not $Auth) {
|        $tp = Get-Variable -Scope Global -Name SI_TokenProvider -ValueOnly -ErrorAction Ignore
|        if ($tp -is [scriptblock]) { $pt = [string](& $tp $Resource); if (-not [string]::IsNullOrWhiteSpace($pt)) { return $pt } }
|    }
|    Initialize-SIAzRestHelpers
|    if (-not $Auth) { $Auth = Resolve-SIAzRestAuth }
|    return (Get-SILogIngestToken -Resource $Resource -Auth $Auth -ForceRefresh:$ForceRefresh)
|}
|
|function ConvertFrom-SIJwtPayload {
|    <# PURE. The claims of a JWT (no signature check -- only used to read tid / exp / appid of our own token). #>
|    param([string]$Token)
|    $parts = ([string]$Token) -split '\.'
|    if ($parts.Count -lt 2) { return $null }
|    $p = $parts[1].Replace('-', '+').Replace('_', '/')
|    switch ($p.Length % 4) { 2 { $p += '==' } 3 { $p += '=' } }
|    try { return ([System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json) } catch { return $null }
|}
|
|function New-SIAzRestError {
|    <# An exception carrying the service's response (Response.StatusCode / Content / Headers), so the existing readers
|       (Get-SIKqlErrorText, the ledger's 412 match, ...) find what the service said. #>
|    param([string]$Message, $Response)
|    $ex = New-Object System.Exception($Message)
|    if ($Response) {
|        $r = [pscustomobject]@{ StatusCode = [int]$Response.StatusCode; Content = [string]$Response.Content; Headers = $Response.Headers }
|        Add-Member -InputObject $ex -NotePropertyName Response -NotePropertyValue $r -Force
|    }
|    return $ex
|}
|
|function Get-SIAzRestStatusName {
|    param([int]$Code)
|    if ($Code -le 0) { return 'NoResponse' }
|    try { return [string][System.Net.HttpStatusCode]$Code } catch { return [string]$Code }
|}
|
|function Invoke-SIAzRestRequest {
|    <#
|        One authenticated REST call with the retry rule:
|          429 / 408 / 5xx / no response -> PLATFORM: wait (Retry-After when sent) and retry in-run
|          401 once                      -> refresh the token, repeat once
|          404 with -AllowNotFound       -> $null
|          any other 4xx                 -> FAIL FAST with the body
|        Returns the response (StatusCode / Content / Bytes / Headers).
|    #>
|    param(
|        [string]$Method = 'GET',
|        [Parameter(Mandatory)][string]$Uri,
|        [ValidateSet('Arm', 'LaQuery', 'Storage', 'KeyVault', 'Graph', 'Monitor')][string]$Audience = 'Arm',
|        $Body,
|        [string]$ContentType = 'application/json',
|        [hashtable]$Headers,
|        [switch]$AllowNotFound,
|        [int[]]$AllowStatus = @(),
|        [switch]$AsBytes,
|        [int]$TimeoutSec = 300,
|        [int]$MaxAttempts = 6,
|        [string]$What = 'Azure request',
|        [hashtable]$Auth,  # another identity than the run's (the platform sign-in reads its Key Vault as the bootstrap identity)
|        # a 2xx body read as it arrives (Invoke-SIAzRestHttp -ReadStream); not through an Invardia support session, whose
|        # recording wrapper hands the answer back whole
|        [scriptblock]$ReadStream
|    )
|    $refreshed = $false; $force = $false
|    # #548: inside an Invardia support session every call SecurityInsight makes as the support app goes through Invardia's
|    # RECORDING wrapper (Invoke-InvardiaSupportRequest: the customer's audit log, fail-closed) -- never a raw token + HTTP.
|    # Every body and every answer goes through the wrapper: a binary body is sent unchanged, a binary answer (a download)
|    # comes back as its ContentBytes (Invardia, 2026-10-10).
|    $viaSupport = (Test-SISupportBodyIsText -Body $Body -ContentType $ContentType) -and (Test-SISupportRequestRoute -Audience $Audience -Auth $Auth -Uri $Uri)
|    for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) {
|        if ($viaSupport) {
|            $h = @{}
|            if ($Headers) { foreach ($k in $Headers.Keys) { $h[$k] = $Headers[$k] } }
|            $r = Invoke-SISupportHttp -Method $Method -Uri $Uri -Headers $h -Body $Body -ContentType $ContentType -AsBytes:$AsBytes -Audience $Audience -TimeoutSec $TimeoutSec
|        } else {
|            $token = Get-SIAzureToken -Audience $Audience -Auth $Auth -ForceRefresh:$force
|            $force = $false
|            $h = @{ 'Authorization' = ('Bearer ' + $token) }
|            if ($Headers) { foreach ($k in $Headers.Keys) { $h[$k] = $Headers[$k] } }
|            if ($ReadStream) { $r = Invoke-SIAzRestHttp -Method $Method -Uri $Uri -Headers $h -Body $Body -ContentType $ContentType -TimeoutSec $TimeoutSec -AsBytes:$AsBytes -ReadStream $ReadStream }
|            else { $r = Invoke-SIAzRestHttp -Method $Method -Uri $Uri -Headers $h -Body $Body -ContentType $ContentType -TimeoutSec $TimeoutSec -AsBytes:$AsBytes }
|        }
|        $code = [int]$r.StatusCode
|        if ($code -ge 200 -and $code -lt 300) { return $r }
|        if ($AllowStatus -contains $code) { return $r }
|        if ($code -eq 404 -and $AllowNotFound) { return $null }
|        if ($code -eq 401 -and -not $refreshed) { $refreshed = $true; $force = $true; continue }
|        $transient = ($code -eq 0 -or $code -eq 408 -or $code -eq 429 -or $code -ge 500)
|        if ($transient -and $attempt -lt $MaxAttempts) {
|            Initialize-SIAzRestHelpers
|            $wait = Get-SILogIngestRetryDelay -RetryAfter ([string]$r.RetryAfter) -Attempt $attempt
|            Write-Verbose ("{0}: HTTP {1}, retrying in {2}s (attempt {3}/{4})" -f $What, $code, $wait, $attempt, $MaxAttempts)
|            Start-Sleep -Seconds $wait
|            continue
|        }
|        $body = [string]$r.Content
|        if ($AsBytes -and $r.Bytes) { try { $body = [System.Text.Encoding]::UTF8.GetString($r.Bytes) } catch { } }
|        $errCode = ''
|        if ($r.Headers -and $r.Headers['x-ms-error-code']) { $errCode = ' ' + [string]$r.Headers['x-ms-error-code'] }
|        $resp = [pscustomobject]@{ StatusCode = $code; Content = $body; Headers = $r.Headers }
|        throw (New-SIAzRestError -Message ("{0} failed. HTTP Status: {1} ({2}){3} Response: {4}" -f $What, $code, (Get-SIAzRestStatusName $code), $errCode, $body) -Response $resp)
|    }
|    throw ("{0} failed after {1} attempts." -f $What, $MaxAttempts)
|}
|
|# =====================================================================================================================
|#  ARM, Resource Graph, Key Vault, Log Analytics
|# =====================================================================================================================
|
|function Test-SIArmBusyError {
|    <# PURE. #564: an ARM refusal that means "another operation on this resource is still running" (HTTP 409
|       OperationInProgress and its per-service names) -- a wait, not a failure. A plain 409 Conflict ("already exists") is NOT. #>
|    param([AllowEmptyString()][string]$Message)
|    [bool]("$Message" -match '(?i)\w*OperationInProgress|operation is (still )?in progress|another operation is (in progress|ongoing|running)|active provisioning operation|is currently being (updated|provisioned)')
|}
|
|function Invoke-SIArmWriteBusyRetry {
|    <#
|        #564 (PIM's install at customer I, 2026-10-10): ONE ARM write (PUT / PATCH / POST / DELETE) with a BOUNDED wait for a busy
|        resource: a write seconds after another change to the same resource is refused "409 OperationInProgress". Waits
|        $global:SI_ArmBusyWaits (default 6 x 20 s) between attempts, RE-READS the resource before each retry (PUT / PATCH /
|        DELETE: what Azure has now), and after a write that had to wait READS IT BACK until it is provisioned (about 60 s).
|        Any other failure is rethrown at once WITH ITS OWN ERROR; the last busy failure is rethrown after the last wait.
|        NOT a closure (a GetNewClosure() block cannot see the functions this file defines). $global:SI_ArmBusySleep
|        { param($Seconds) } is the test seam for the waits. Returns the response (Invoke-SIAzRestRequest's shape).
|    #>
|    param([Parameter(Mandatory)][string]$Method, [Parameter(Mandatory)][string]$Uri, $Json, [switch]$AllowNotFound, [string]$What = 'Azure Resource Manager write')
|    $waits = @(20, 20, 20, 20, 20, 20)
|    $gw = Get-Variable -Scope Global -Name SI_ArmBusyWaits -ValueOnly -ErrorAction Ignore
|    if ($null -ne $gw) { $waits = @($gw | ForEach-Object { [int]$_ }) }
|    $sleep = Get-Variable -Scope Global -Name SI_ArmBusySleep -ValueOnly -ErrorAction Ignore
|    $verb = $Method.ToUpperInvariant()
|    $resourceUri = if ($verb -in 'PUT', 'PATCH', 'DELETE') { $Uri } else { $null }
|    $try = 0; $waited = $false
|    while ($true) {
|        try { $r = Invoke-SIAzRestRequest -Method $Method -Uri $Uri -Body $Json -AllowNotFound:$AllowNotFound -What $What; break }
|        catch {
|            if (-not (Test-SIArmBusyError -Message ([string]$_.Exception.Message)) -or $try -ge $waits.Count) { throw }
|            $w = [int]$waits[$try]; $try++; $waited = $true
|            Write-Host ('       Azure is still busy with another change to {0} -- waiting {1} s, then trying again ({2}/{3}) ...' -f (($Uri -replace '\?.*$', '') -split '/')[-1], $w, $try, $waits.Count) -ForegroundColor DarkYellow
|            if ($w -gt 0) { if ($sleep -is [scriptblock]) { & $sleep $w } else { Start-Sleep -Seconds $w } }
|            # re-read before the retry: what Azure has now (never fails the write -- the retry decides)
|            if ($resourceUri) { try { $null = Invoke-SIAzRestRequest -Method GET -Uri $resourceUri -AllowNotFound -What ('Reading ' + $What) } catch { } }
|        }
|    }
|    if ($waited -and $verb -in 'PUT', 'PATCH') {
|        # read back: the write that waited is followed until Azure has provisioned it (bounded, about 60 s)
|        for ($i = 0; $i -lt 6; $i++) {
|            $back = $null
|            try { $back = Invoke-SIAzRestRequest -Method GET -Uri $resourceUri -AllowNotFound -What ('Reading back ' + $What) } catch { break }
|            $ps = ''
|            try { $ps = [string](($back.Content | ConvertFrom-Json).properties.provisioningState) } catch { $ps = '' }
|            if (-not $ps -or $ps -in 'Succeeded', 'Failed', 'Canceled', 'Cancelled') { break }
|            if ($sleep -is [scriptblock]) { & $sleep 10 } else { Start-Sleep -Seconds 10 }
|        }
|    }
|    $r
|}
|
|function Invoke-SIArm {
|    <#
|        Azure Resource Manager. -Path is '/subscriptions/...' (or a full https:// URL, e.g. a nextLink); -ApiVersion is
|        appended when the path has none. Returns the parsed body ($null for a 404 with -AllowNotFound).
|        -List returns every item of a list, following nextLink.
|    #>
|    param(
|        [string]$Method = 'GET',
|        [Parameter(Mandatory)][string]$Path,
|        [string]$ApiVersion,
|        $Body,
|        [switch]$AllowNotFound,
|        [switch]$List
|    )
|    $uri = if ($Path -match '^https://') { $Path } else { 'https://management.azure.com' + $Path }
|    if ($ApiVersion -and $uri -notmatch '[?&]api-version=') { $uri += $(if ($uri -match '\?') { '&' } else { '?' }) + 'api-version=' + $ApiVersion }
|    $json = if ($null -ne $Body -and -not ($Body -is [string])) { $Body | ConvertTo-Json -Depth 50 -Compress } else { $Body }
|    # #564 (PIM's install at customer I, 2026-10-10): an ARM POST ACTION with no body (listSecrets, listCredentials, listKeys,
|    # sharedKeys, a revision restart, a provider register) sends '{}' -- an empty body with a JSON content type was
|    # refused with HTTP 415.
|    if ($Method.ToUpperInvariant() -eq 'POST' -and ($null -eq $json -or ([string]$json) -eq '')) { $json = '{}' }
|    $what = 'Azure Resource Manager {0} {1}' -f $Method, ($uri -replace '\?.*$', '')
|    if (-not $List) {
|        if ($Method.ToUpperInvariant() -eq 'GET') { $r = Invoke-SIAzRestRequest -Method $Method -Uri $uri -Body $json -AllowNotFound:$AllowNotFound -What $what }
|        else { $r = Invoke-SIArmWriteBusyRetry -Method $Method -Uri $uri -Json $json -AllowNotFound:$AllowNotFound -What $what }
|        if (-not $r -or [string]::IsNullOrWhiteSpace([string]$r.Content)) { return $null }
|        return ($r.Content | ConvertFrom-Json)
|    }
|    $items = [System.Collections.Generic.List[object]]::new()
|    $next = $uri
|    while ($next) {
|        $r = Invoke-SIAzRestRequest -Method 'GET' -Uri $next -AllowNotFound:$AllowNotFound -What $what
|        if (-not $r) { break }
|        $page = $r.Content | ConvertFrom-Json
|        foreach ($v in @($page.value)) { if ($null -ne $v) { [void]$items.Add($v) } }
|        $next = [string]$page.nextLink
|    }
|    return $items.ToArray()
|}
|
|function Search-SIResourceGraph {
|    <# Resource Graph: EVERY row of -Query, following $skipToken. -Subscription / -ManagementGroup scope it; neither =
|       every subscription the identity can read (as Search-AzGraph without them). #>
|    param(
|        [Parameter(Mandatory)][string]$Query,
|        [string[]]$Subscription,
|        [string[]]$ManagementGroup,
|        [int]$PageSize = 1000
|    )
|    $rows = [System.Collections.Generic.List[object]]::new()
|    $skip = $null
|    do {
|        $page = Invoke-SIResourceGraphPage -Query $Query -Subscription $Subscription -ManagementGroup $ManagementGroup -First $PageSize -SkipToken $skip
|        foreach ($d in @($page.Data)) { if ($null -ne $d) { [void]$rows.Add($d) } }
|        $skip = [string]$page.SkipToken
|    } while ($skip)
|    return $rows.ToArray()
|}
|
|function Invoke-SIResourceGraphPage {
|    <# ONE Resource Graph page: @{ Data; SkipToken; TotalRecords }. #>
|    param([string]$Query, [string[]]$Subscription, [string[]]$ManagementGroup, [int]$First = 1000, [int]$Skip = 0, [string]$SkipToken)
|    $opt = [ordered]@{ resultFormat = 'objectArray'; '$top' = $First }
|    if ($Skip -gt 0) { $opt['$skip'] = $Skip }
|    if ($SkipToken) { $opt['$skipToken'] = $SkipToken }
|    $body = [ordered]@{ query = $Query; options = $opt }
|    $subs = @(@($Subscription) | Where-Object { -not [string]::IsNullOrWhiteSpace([string]$_) })
|    $mgs  = @(@($ManagementGroup) | Where-Object { -not [string]::IsNullOrWhiteSpace([string]$_) })
|    if ($subs.Count) { $body['subscriptions'] = [string[]]$subs }
|    if ($mgs.Count) { $body['managementGroups'] = [string[]]$mgs }
|    $r = Invoke-SIAzRestRequest -Method POST -Uri 'https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01' `
|             -Body ($body | ConvertTo-Json -Depth 10 -Compress) -What 'Resource Graph query'
|    $j = $r.Content | ConvertFrom-Json
|    $tok = $null
|    if ($j.PSObject.Properties['$skipToken']) { $tok = [string]$j.'$skipToken' }
|    return [pscustomobject]@{ Data = @($j.data); SkipToken = $tok; TotalRecords = $j.totalRecords }
|}
|
|function Get-SIKeyVaultSecretValue {
|    <# One Key Vault secret as plain text; $null when the secret does not exist. #>
|    param([Parameter(Mandatory)][string]$VaultName, [Parameter(Mandatory)][string]$Name, [string]$Version, [hashtable]$Auth)
|    $j = Get-SIKeyVaultSecretRaw -VaultName $VaultName -Name $Name -Version $Version -Auth $Auth
|    if (-not $j) { return $null }
|    return [string]$j.value
|}
|
|function Get-SIKeyVaultSecretRaw {
|    param([string]$VaultName, [string]$Name, [string]$Version, [hashtable]$Auth)
|    $v = if ($Version) { '/' + $Version } else { '' }
|    $uri = 'https://{0}.vault.azure.net/secrets/{1}{2}?api-version=7.4' -f $VaultName, [uri]::EscapeDataString($Name), $v
|    $r = Invoke-SIAzRestRequest -Method GET -Uri $uri -Audience KeyVault -AllowNotFound -Auth $Auth -What ("Key Vault secret '{0}' in '{1}'" -f $Name, $VaultName)
|    if (-not $r) { return $null }
|    return ($r.Content | ConvertFrom-Json)
|}
|
|function ConvertTo-SIAzLaCellString {
|    <# One Log Analytics cell, as Az.OperationalInsights hands it to callers: TEXT. Strings and dates stay as the
|       service sent them, numbers keep their JSON spelling, booleans are 'true' / 'false', null stays null, nested
|       values are JSON text. #>
|    param($Value)
|    if ($null -eq $Value) { return $null }
|    if ($Value -is [string]) { return $Value }
|    if ($Value -is [bool]) { if ($Value) { return 'true' } else { return 'false' } }
|    if ($Value -is [datetime]) { return $Value.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.FFFFFFFZ', [System.Globalization.CultureInfo]::InvariantCulture) }
|    if ($Value -is [System.IFormattable]) { return $Value.ToString($null, [System.Globalization.CultureInfo]::InvariantCulture) }
|    return (ConvertTo-Json -InputObject $Value -Depth 20 -Compress)
|}
|
|function ConvertFrom-SILaQueryJson {
|    <#
|        The Log Analytics query response -> @{ Tables = @( @{ Name; Columns = @(@{name;type}); Rows = @(@(cells as text)) } ); Error }.
|        pwsh 7: System.Text.Json, so a date stays the exact text the service sent (ConvertFrom-Json would turn it into a
|        local DateTime). Windows PowerShell 5.1: ConvertFrom-Json, which leaves dates as text.
|    #>
|    param([Parameter(Mandatory)][string]$Json)
|    $tables = [System.Collections.Generic.List[object]]::new()
|    $err = $null
|    if ($PSVersionTable.PSEdition -eq 'Core') {
|        $doc = [System.Text.Json.JsonDocument]::Parse($Json)
|        try {
|            $root = $doc.RootElement
|            $tEl = [System.Text.Json.JsonElement]::new()
|            if ($root.TryGetProperty('tables', [ref]$tEl)) {
|                foreach ($t in $tEl.EnumerateArray()) {
|                    $cols = [System.Collections.Generic.List[object]]::new()
|                    foreach ($c in $t.GetProperty('columns').EnumerateArray()) {
|                        $ty = [System.Text.Json.JsonElement]::new(); $tyS = ''
|                        if ($c.TryGetProperty('type', [ref]$ty)) { $tyS = $ty.GetString() }
|                        [void]$cols.Add([pscustomobject]@{ name = $c.GetProperty('name').GetString(); type = $tyS })
|                    }
|                    $rows = [System.Collections.Generic.List[object]]::new()
|                    foreach ($row in $t.GetProperty('rows').EnumerateArray()) {
|                        $cells = [System.Collections.Generic.List[object]]::new()
|                        foreach ($cell in $row.EnumerateArray()) {
|                            switch ($cell.ValueKind.ToString()) {
|                                'String' { [void]$cells.Add($cell.GetString()) }
|                                'Null'   { [void]$cells.Add($null) }
|                                'True'   { [void]$cells.Add('true') }
|                                'False'  { [void]$cells.Add('false') }
|                                default  { [void]$cells.Add($cell.GetRawText()) }
|                            }
|                        }
|                        [void]$rows.Add($cells.ToArray())
|                    }
|                    $nm = [System.Text.Json.JsonElement]::new(); $nmS = ''
|                    if ($t.TryGetProperty('name', [ref]$nm)) { $nmS = $nm.GetString() }
|                    [void]$tables.Add([pscustomobject]@{ Name = $nmS; Columns = $cols.ToArray(); Rows = $rows.ToArray() })
|                }
|            }
|            $eEl = [System.Text.Json.JsonElement]::new()
|            if ($root.TryGetProperty('error', [ref]$eEl) -and $eEl.ValueKind.ToString() -ne 'Null') { $err = ($eEl.GetRawText() | ConvertFrom-Json) }
|        } finally { $doc.Dispose() }
|    } else {
|        $j = $Json | ConvertFrom-Json
|        foreach ($t in @($j.tables)) {
|            if ($null -eq $t) { continue }
|            $rows = [System.Collections.Generic.List[object]]::new()
|            foreach ($row in @($t.rows)) {
|                $cells = [System.Collections.Generic.List[object]]::new()
|                foreach ($cell in @($row)) { [void]$cells.Add((ConvertTo-SIAzLaCellString $cell)) }
|                [void]$rows.Add($cells.ToArray())
|            }
|            [void]$tables.Add([pscustomobject]@{ Name = [string]$t.name; Columns = @($t.columns); Rows = $rows.ToArray() })
|        }
|        if ($j.PSObject.Properties['error'] -and $j.error) { $err = $j.error }
|    }
|    return [pscustomobject]@{ Tables = $tables.ToArray(); Error = $err }
|}
|
|function Get-SILaCompactRowType {
|    <#
|        #711. A .NET class for one column list: one public text property per column, in the column order, built from the
|        row's values in one call (new(string[])). Built once per column list and process (Add-Type, pwsh 7 / .NET 8) and
|        reused. $null when it cannot be built -- a column name that is not a plain identifier, two names that differ only in
|        case (PowerShell reads properties without case), Windows PowerShell -- and the caller keeps PSCustomObject rows.
|    #>
|    param([Parameter(Mandatory)][AllowEmptyCollection()][string[]]$Names)
|    if ($PSVersionTable.PSEdition -ne 'Core' -or $Names.Count -eq 0) { return $null }
|    if ($null -eq $script:SILaCompactRowTypes) { $script:SILaCompactRowTypes = @{} }
|    $key = ($Names -join "`n")
|    if ($script:SILaCompactRowTypes.ContainsKey($key)) { return $script:SILaCompactRowTypes[$key] }
|    $type = $null
|    try {
|        $seen = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::OrdinalIgnoreCase)
|        foreach ($n in $Names) { if ($n -notmatch '^[A-Za-z_][A-Za-z0-9_]*$' -or -not $seen.Add($n)) { throw ('not a plain column name: {0}' -f $n) } }
|        $sha = [System.Security.Cryptography.SHA256]::Create()
|        try { $h = ([System.BitConverter]::ToString($sha.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($key))) -replace '-', '').Substring(0, 20) } finally { $sha.Dispose() }
|        $cls = 'R' + $h
|        $full = 'SecurityInsight.LaRows.' + $cls
|        $type = $full -as [type]
|        if ($null -eq $type) {
|            $sb = New-Object System.Text.StringBuilder
|            [void]$sb.Append('namespace SecurityInsight.LaRows { public sealed class ').Append($cls).Append(' { ')
|            foreach ($n in $Names) { [void]$sb.Append('public string @').Append($n).Append(' { get; set; } ') }
|            [void]$sb.Append('public ').Append($cls).Append('(string[] v) { ')
|            for ($i = 0; $i -lt $Names.Count; $i++) { [void]$sb.Append('this.@').Append($Names[$i]).Append(' = v[').Append($i).Append(']; ') }
|            [void]$sb.Append('} } }')
|            Add-Type -TypeDefinition $sb.ToString() -Language CSharp -ErrorAction Stop
|            $type = $full -as [type]
|        }
|    } catch { $type = $null }
|    $script:SILaCompactRowTypes[$key] = $type
|    return $type
|}
|
|function ConvertFrom-SILaQueryRows {
|    <#
|        The Log Analytics query response AS THE BYTES THE SERVICE SENT -> @{ Rows; Error }: the primary table's rows, one
|        object per row, one TEXT property per column -- the same rows Invoke-SILaQuery hands out as .Results.
|        For large answers (Invoke-SILaQuery -RowsOnly): the bytes are parsed where they are. The answer is never also held
|        as one text (twice its size), as a second copy of every table, or as a list of cells per row -- on a large install
|        those copies together ran a job out of memory. pwsh 7 only (System.Text.Json).
|    #>
|    param([Parameter(Mandatory)][AllowEmptyCollection()][byte[]]$Bytes)
|    $rows = [System.Collections.Generic.List[object]]::new()
|    $cols = [System.Collections.Generic.List[object]]::new()
|    $err = $null
|    $doc = [System.Text.Json.JsonDocument]::Parse([System.ReadOnlyMemory[byte]]::new($Bytes))
|    try {
|        $root = $doc.RootElement
|        $tEl = [System.Text.Json.JsonElement]::new()
|        if ($root.TryGetProperty('tables', [ref]$tEl)) {
|            # the table named PrimaryResult, else the first one -- as .Results has always been chosen
|            $have = $false
|            $pick = [System.Text.Json.JsonElement]::new()
|            foreach ($t in $tEl.EnumerateArray()) {
|                $nm = [System.Text.Json.JsonElement]::new(); $nmS = ''
|                if ($t.TryGetProperty('name', [ref]$nm)) { $nmS = [string]$nm.GetString() }
|                if (-not $have) { $pick = $t; $have = $true }
|                if ($nmS -eq 'PrimaryResult') { $pick = $t; break }
|            }
|            if ($have) {
|                $names = [System.Collections.Generic.List[string]]::new()
|                foreach ($c in $pick.GetProperty('columns').EnumerateArray()) {
|                    $names.Add([string]$c.GetProperty('name').GetString())
|                    $ty = [System.Text.Json.JsonElement]::new(); $tyS = $null
|                    if ($c.TryGetProperty('type', [ref]$ty)) { $tyS = $ty.GetString() }
|                    $cols.Add([pscustomobject]@{ name = $names[$names.Count - 1]; type = $tyS })
|                }
|                $nCols = $names.Count
|                # #711: a caller that keeps the rows for long (Risk Analysis' lookups) asks for COMPACT rows -- one small
|                # .NET object per row with one text property per column (Get-SILaCompactRowType), not a PSCustomObject
|                # (measured on the test VM: ~6 KB per row of 11 columns as a PSCustomObject). Read the same way by
|                # every reader ($row.Col, $row.PSObject.Properties['Col'].Value). Not available -> the rows as always.
|                $compactType = $null
|                if ([bool]$global:SI_LaCompactRows) { $compactType = Get-SILaCompactRowType -Names $names.ToArray() }
|                if ($null -ne $compactType) {
|                    # a short value that repeats (a tier, a flag, an empty text, a short factor list) is held once per read
|                    $pool = [System.Collections.Generic.Dictionary[string, string]]::new([System.StringComparer]::Ordinal)
|                    foreach ($row in $pick.GetProperty('rows').EnumerateArray()) {
|                        # a null cell is left as the array's own null (assigning $null to a [string] element would make it '')
|                        $vals = [string[]]::new($nCols)
|                        $i = 0
|                        foreach ($cell in $row.EnumerateArray()) {
|                            if ($i -ge $nCols) { break }
|                            $kind = $cell.ValueKind.ToString()
|                            if ($kind -ne 'Null') {
|                                $s = if ($kind -eq 'String') { $cell.GetString() } elseif ($kind -eq 'True') { 'true' } elseif ($kind -eq 'False') { 'false' } else { $cell.GetRawText() }
|                                if ($s.Length -le 32) { $p0 = $null; if ($pool.TryGetValue($s, [ref]$p0)) { $s = $p0 } else { $pool[$s] = $s } }
|                                $vals[$i] = $s
|                            }
|                            $i++
|                        }
|                        [void]$rows.Add($compactType::new($vals))
|                    }
|                    $nCols = -1
|                }
|                if ($nCols -ge 0) {
|                foreach ($row in $pick.GetProperty('rows').EnumerateArray()) {
|                    $o = [ordered]@{}
|                    $i = 0
|                    foreach ($cell in $row.EnumerateArray()) {
|                        if ($i -ge $nCols) { break }
|                        $name = $names[$i]
|                        $kind = $cell.ValueKind.ToString()
|                        if ($kind -eq 'String') { $o[$name] = $cell.GetString() }
|                        elseif ($kind -eq 'Null') { $o[$name] = $null }
|                        elseif ($kind -eq 'True') { $o[$name] = 'true' }
|                        elseif ($kind -eq 'False') { $o[$name] = 'false' }
|                        else { $o[$name] = $cell.GetRawText() }
|                        $i++
|                    }
|                    # a row shorter than its columns: the missing ones are empty, as before
|                    for (; $i -lt $nCols; $i++) { $o[$names[$i]] = $null }
|                    [void]$rows.Add([pscustomobject]$o)
|                }
|                }
|            }
|        }
|        $eEl = [System.Text.Json.JsonElement]::new()
|        if ($root.TryGetProperty('error', [ref]$eEl) -and $eEl.ValueKind.ToString() -ne 'Null') { $err = ($eEl.GetRawText() | ConvertFrom-Json) }
|    } finally { $doc.Dispose() }
|    return [pscustomobject]@{ Rows = $rows.ToArray(); Columns = $cols.ToArray(); Error = $err }
|}
|
|function Get-SILaServiceRowLimit {
|    <# The most rows ONE Log Analytics query answer carries (the service's own limit). An answer holding exactly that many
|       rows cannot be told from an answer the service cut there. $global:SI_LaServiceRowLimit overrides it (tests). #>
|    $v = 0L
|    try { $v = [long]$global:SI_LaServiceRowLimit } catch { $v = 0L }
|    if ($v -gt 0) { return $v }
|    return 500000L
|}
|
|function Get-SILaPartialVerdict {
|    <#
|        PURE. What a Log Analytics partial answer (the "error" object beside the rows of an HTTP 200 answer) says, read from
|        its LEAVES (the innermost error objects -- the outer ones are generic). Returns @{ Kind; Code; Detail; Tables }:
|          Unresolved  every leaf is "Failed to resolve table or column expression named 'SI_..._CL'": a `union isfuzzy=true`
|                      leg over a SecurityInsight table this workspace does not have yet. The answer IS the whole result (the
|                      missing table has no rows) -- the one partial answer that is not a cut one.
|          Limit       a leaf names a limit (rows / size / time / memory): the answer is CUT; a smaller read fixes it.
|          Other       anything else: the answer is short, and a smaller read does not fix it.
|        The same reading as Risk Analysis' own (RA-LaPartedRead.ps1 Get-RALaPartialVerdict); kept here so every reader of
|        Log Analytics refuses a cut answer, not only Risk Analysis.
|        -MayBeMissing (2026-10-23): other tables the CALLER names that this workspace may not have (the capability probe's
|        SecurityIncident / SecurityAlert in a workspace without Sentinel): a leaf that cannot resolve one of them is
|        Unresolved too -- the answer is whole, the table has no rows. Only the tables named; never any other.
|    #>
|    param([AllowNull()][object]$ErrorObject, [string[]]$MayBeMissing = @())
|    $leaves = New-Object System.Collections.Generic.List[string]
|    $all = New-Object System.Collections.Generic.List[string]
|    $codes = New-Object System.Collections.Generic.List[string]
|    $get = {
|        param($o, $n)
|        if ($null -eq $o) { return $null }
|        if ($o -is [System.Collections.IDictionary]) { if ($o.Contains($n)) { return $o[$n] }; return $null }
|        $p = $o.PSObject.Properties[$n]; if ($p) { return $p.Value }; return $null
|    }
|    $stack = New-Object System.Collections.Stack
|    if ($null -ne $ErrorObject -and $ErrorObject -isnot [string]) { $stack.Push($ErrorObject) }
|    $visited = 0
|    while ($stack.Count -gt 0 -and $visited -lt 256) {
|        $o = $stack.Pop(); $visited++
|        if ($null -eq $o -or $o -is [string]) { continue }
|        $m = [string](& $get $o 'message'); $c = [string](& $get $o 'code')
|        if ($c -and $codes.Count -lt 3 -and -not $codes.Contains($c)) { $codes.Add($c) }
|        if ($m) { $all.Add($m) }
|        $children = New-Object System.Collections.Generic.List[object]
|        $ie = & $get $o 'innererror'; if ($null -ne $ie -and $ie -isnot [string]) { $children.Add($ie) }
|        $ds = & $get $o 'details'
|        if ($null -ne $ds) { foreach ($d in @($ds)) { if ($null -ne $d -and $d -isnot [string]) { $children.Add($d) } } }
|        if ($children.Count -eq 0) { if ($m) { $leaves.Add($m) } }
|        else { for ($i = $children.Count - 1; $i -ge 0; $i--) { $stack.Push($children[$i]) } }
|    }
|    if ($null -ne $ErrorObject -and $ErrorObject -is [string]) { $leaves.Add([string]$ErrorObject); $all.Add([string]$ErrorObject) }
|    $generic = '^(There were some errors when processing your query\.?|Something went wrong processing your query on the server\.?)$'
|    $specific = @($all | Where-Object { $_ -notmatch $generic } | Select-Object -Unique)
|    $detail = (@($specific) -join '; ')
|    if (-not $detail) { $detail = (@($all | Select-Object -Unique) -join '; ') }
|    if ($detail.Length -gt 400) { $detail = $detail.Substring(0, 400) + '...' }
|    $code = (@($codes) -join '/')
|    # a 'union' leaf says "table expression", a 'where' leaf "table or column expression" (both: the table is not there)
|    $rx = "Failed to resolve table (?:or column )?expression named '(?<t>[A-Za-z0-9_]+)'"
|    $okMissing = { param($t) ($t -match '^SI_[A-Za-z0-9_]+_CL$') -or (@($MayBeMissing | Where-Object { $_ -and [string]$_ -ieq $t }).Count -gt 0) }
|    $tables = New-Object System.Collections.Generic.List[string]
|    $leafSpecific = @($leaves | Where-Object { $_ -notmatch $generic })
|    $allResolve = ($leafSpecific.Count -gt 0)
|    foreach ($l in $leafSpecific) {
|        $mm = [regex]::Match($l, $rx)
|        if (-not $mm.Success -or -not (& $okMissing $mm.Groups['t'].Value)) { $allResolve = $false; break }
|        if (-not $tables.Contains($mm.Groups['t'].Value)) { $tables.Add($mm.Groups['t'].Value) }
|    }
|    if ($allResolve) { return @{ Kind = 'Unresolved'; Code = $code; Detail = $detail; Tables = $tables.ToArray() } }
|    $limitRx = '(?i)limit|exceeded|too large|E_QUERY_RESULT_SET_TOO_LARGE|timed out|timeout|E_RUNAWAY|out of memory|memory|truncat|cancell?ed|preempted'
|    if (@($all | Where-Object { $_ -match $limitRx }).Count -gt 0) { return @{ Kind = 'Limit'; Code = $code; Detail = $detail; Tables = @() } }
|    return @{ Kind = 'Other'; Code = $code; Detail = $detail; Tables = @() }
|}
|
|function Test-SILaAnswerWhole {
|    <#
|        PURE. Is a Log Analytics answer the WHOLE result? -ErrorObject: the partial-error object beside the rows; -Rows: how
|        many rows the answer held. Returns @{ Whole; Kind; Code; Detail; Tables; Rows }:
|          no error and fewer rows than the service's own row limit   -> whole
|          an Unresolved partial error (a missing SI table in a fuzzy union)  -> whole (the missing table has no rows)
|          a Limit / Other partial error                              -> NOT whole
|          no error, but exactly as many rows as the service's limit  -> NOT whole (Limit): it cannot be told from a cut answer
|    #>
|    # -MayBeMissing: as Get-SILaPartialVerdict (the tables the caller names that the workspace may not have)
|    param([AllowNull()][object]$ErrorObject, [long]$Rows = 0, [string[]]$MayBeMissing = @())
|    if ($null -ne $ErrorObject) {
|        $v = Get-SILaPartialVerdict -ErrorObject $ErrorObject -MayBeMissing $MayBeMissing
|        return @{ Whole = ($v.Kind -eq 'Unresolved'); Kind = $v.Kind; Code = $v.Code; Detail = $v.Detail; Tables = $v.Tables; Rows = $Rows }
|    }
|    $cap = Get-SILaServiceRowLimit
|    if ($Rows -ge $cap) {
|        $d = [string]::Format([System.Globalization.CultureInfo]::InvariantCulture, 'the answer holds {0:N0} rows, the most one answer carries (the service''s limit of {1:N0} rows) -- it cannot be told from a cut answer', $Rows, $cap)
|        return @{ Whole = $false; Kind = 'Limit'; Code = 'RowLimit'; Detail = $d; Tables = @(); Rows = $Rows }
|    }
|    return @{ Whole = $true; Kind = ''; Code = ''; Detail = ''; Tables = @(); Rows = $Rows }
|}
|
|function New-SILaCutAnswerError {
|    <#
|        The error a refused cut answer becomes (Invoke-SILaQuery without -AllowPartial). An ErrorRecord whose exception
|        carries the service's own words three ways, so every classifier that reads a failed query finds them:
|          * the message: "Log Analytics returned a PARTIAL answer (<code>: <detail>) -- ..."; a Limit also says "Query
|            execution has exceeded the allowed limits" (the text Risk Analysis' bucket logic makes a slice smaller on);
|          * Exception.Response.Content and ErrorDetails: the error object as JSON (Get-SIKqlErrorText -> the data sync's
|            "too large" check, Test-SIDataResponseTooLarge, cuts that page in two);
|          * Exception.Data: SILaPartial / SIRALaPartial = the kind, SIRALaPartialRows = the rows the short answer held (Risk
|            Analysis' parted reader measures with them).
|    #>
|    param([Parameter(Mandatory)][hashtable]$Verdict, [AllowNull()][object]$ErrorObject, [string]$WorkspaceId = '')
|    $msg = if ($Verdict.Kind -eq 'Limit') {
|        "Log Analytics returned a PARTIAL answer ({0}: {1}) -- Query execution has exceeded the allowed limits; the rows it returned are not the whole result and were not used" -f $Verdict.Code, $Verdict.Detail
|    } else {
|        "Log Analytics returned a PARTIAL answer ({0}: {1}) -- the rows it returned are not the whole result and were not used" -f $Verdict.Code, $Verdict.Detail
|    }
|    $json = ''
|    if ($null -ne $ErrorObject) { try { $json = ConvertTo-Json -InputObject ([pscustomobject]@{ error = $ErrorObject }) -Depth 12 -Compress } catch { $json = [string]$ErrorObject } }
|    else { $json = ConvertTo-Json -InputObject ([pscustomobject]@{ error = [pscustomobject]@{ code = [string]$Verdict.Code; message = [string]$Verdict.Detail } }) -Depth 4 -Compress }
|    $ex = New-SIAzRestError -Message $msg -Response ([pscustomobject]@{ StatusCode = 200; Content = $json; Headers = @{} })
|    $ex.Data['SILaPartial'] = [string]$Verdict.Kind
|    $ex.Data['SIRALaPartial'] = [string]$Verdict.Kind
|    $ex.Data['SIRALaPartialRows'] = [long]$Verdict.Rows
|    $er = New-Object System.Management.Automation.ErrorRecord($ex, 'SILaQueryPartial', [System.Management.Automation.ErrorCategory]::LimitsExceeded, $WorkspaceId)
|    $er.ErrorDetails = New-Object System.Management.Automation.ErrorDetails($json)
|    return $er
|}
|
|function Test-SILaCutAnswerError {
|    <# PURE. Was this failure a cut answer Invoke-SILaQuery refused (New-SILaCutAnswerError)? -Kind: only that kind. #>
|    param([AllowNull()][object]$Err, [string]$Kind = '')
|    $ex = $null
|    if ($Err -is [System.Management.Automation.ErrorRecord]) { $ex = $Err.Exception } elseif ($Err -is [System.Exception]) { $ex = $Err }
|    while ($null -ne $ex) {
|        if ($ex.Data -and $ex.Data.Contains('SILaPartial')) { return ((-not $Kind) -or ([string]$ex.Data['SILaPartial'] -eq $Kind)) }
|        $ex = $ex.InnerException
|    }
|    return $false
|}
|
|function Invoke-SILaQuery {
|    <#
|        A KQL query on the Log Analytics DATA PLANE: POST https://api.loganalytics.io/v1/workspaces/{id}/query. Not the
|        ARM /api/query route, which hides the semantic error behind a generic one.
|        Returns the shape Invoke-AzOperationalInsightsQuery returns and every caller reads:
|            .Results   the primary table's rows, one object per row, one TEXT property per column (as Az hands them)
|            .Columns   the primary table's columns (name / type) -- what the workbooks type their columns from
|            .Tables    ONE entry: the primary table's Name and Columns, NO rows (RowsOmitted). The rows are in .Results only;
|                       the answer is never held a second time as tables beside them (#639). No caller reads table rows.
|            .Error     the partial-error object (or $null) -- only ever set beside rows that ARE the whole result (a missing SI
|                       table in a fuzzy union), or with -AllowPartial
|            .RowCount  the rows the answer held (with -OnPage: the rows handed to it)
|        A CUT ANSWER IS REFUSED (#639, working rule 4). Log Analytics answers HTTP 200 with the rows it got to AND an error
|        object when it stopped early (a result over its row / size limit, a part that timed out); an answer with exactly as
|        many rows as the service's own row limit cannot be told from one cut there. Such an answer THROWS
|        (New-SILaCutAnswerError: the service's words, the kind, the rows it held) -- a cut answer is never handed out as
|        whole. -AllowPartial: the caller reads .Error itself and decides (the rows and the error come back as before, and
|        .Partial says the kind). A read that pages (its query keys the rows) catches the "too large" refusal and reads that
|        page again in smaller pages -- the refusal carries the same words the cut answer did.
|        -OnPage { param($Rows) }: the rows are handed on a PAGE at a time as they arrive (about -PageBytes of answer each,
|        the size measured from the answer's own bytes) and never collected -- memory is one page, whatever the size of the
|        answer. .Results is then empty. The pages are PROVISIONAL until this call returns: a cut answer (said at the END of
|        the answer) or a read that fails half-way throws AFTER pages were handed on, so a caller stages the pages and keeps
|        them only when the call returned. Without the streaming reader (Windows PowerShell, or it cannot be built) the
|        answer is read the older way and then handed on in pages of the same size.
|        THE LEAN READ IS THE DEFAULT (#639): on pwsh 7 the answer arrives as bytes and its rows are read from those bytes
|        (ConvertFrom-SILaQueryRows) -- never also held as one text (twice its size) or as a list of cells per row. The same
|        rows and the same text values as before. Windows PowerShell (no System.Text.Json) reads the text, as always.
|        -WorkspaceId is the workspace's customer id (GUID). -Wait = server timeout in seconds (Prefer: wait=N).
|        -RowsOnly is kept for the callers that name it; it is what every read does now.
|        A refused query throws with the service's own code and message, e.g.
|            "Operation returned an invalid status code 'BadRequest' -- BadArgumentError/SemanticError/SEM0100: ..."
|        and carries the body in Exception.Response.Content and ErrorDetails -- what SI-KqlError.ps1 reads.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$WorkspaceId,
|        [Parameter(Mandatory)][string]$Query,
|        [int]$Wait = 0,
|        [timespan]$Timespan = [timespan]::Zero,
|        [int]$MaxAttempts = 4,
|        [switch]$RowsOnly,
|        # the caller reads .Error itself and decides what a cut answer means (never the default)
|        [switch]$AllowPartial,
|        # the rows a page at a time, never collected (see above)
|        [scriptblock]$OnPage,
|        [long]$PageBytes = 4MB
|    )
|    Initialize-SIAzRestHelpers
|    if ($OnPage) {
|        return (Invoke-SILaQueryPaged -WorkspaceId $WorkspaceId -Query $Query -Wait $Wait -Timespan $Timespan -MaxAttempts $MaxAttempts -AllowPartial:$AllowPartial -OnPage $OnPage -PageBytes $PageBytes)
|    }
|    $uri = 'https://api.loganalytics.io/v1/workspaces/{0}/query' -f $WorkspaceId.Trim()
|    $body = [ordered]@{ query = $Query }
|    if ($Timespan -gt [timespan]::Zero) { $body['timespan'] = [System.Xml.XmlConvert]::ToString($Timespan) }
|    $headers = @{}
|    $timeout = 300
|    # #882 (A4): Log Analytics stops a query at 3 minutes unless asked to wait -- every query asks for its maximum (10 minutes)
|    if ($Wait -le 0) { $Wait = 600 }
|    if ($Wait -gt 0) { $headers['Prefer'] = ('wait={0}' -f $Wait); $timeout = $Wait + 60 }
|    # the answer as bytes wherever it can be read from them (pwsh 7) -- the lean read is the default (#639)
|    $asBytes = ([bool]$RowsOnly -or $PSVersionTable.PSEdition -eq 'Core')
|    # #730: Risk Analysis' reads (its lookups -- SI_LaCompactRows -- and its Log Analytics answers -- SI_LaStreamRows) are
|    # read AS THEY ARRIVE (SI-LaStreamRead.ps1): the same rows, the answer never held whole. Everything else reads as before.
|    $readStream = $null
|    if ($PSVersionTable.PSEdition -eq 'Core' -and ([bool]$global:SI_LaCompactRows -or [bool]$global:SI_LaStreamRows) -and
|        (Get-Command -Name Get-SILaStreamReaderType -ErrorAction Ignore)) {
|        if (Get-SILaStreamReaderType) {
|            $__lsCompact = [bool]$global:SI_LaCompactRows
|            # (no closure: it runs inside this call, so $__lsCompact is seen; a closure would not see this file's functions)
|            # #836: a failed stream read answers a marker -- read again below the older way, never an error of the query
|            $readStream = { param($s) Read-SILaQueryStreamSafe -Stream $s -Compact:$__lsCompact }
|        } else {
|            # #836: never silent -- one line on the run log says the older read is used and why
|            Write-SILaStreamFallback -Once -Reason ([string]$global:SI_LaStreamReaderOff)
|        }
|    }
|    $rq = @{ Method = 'POST'; Uri = $uri; Audience = 'LaQuery'; Body = ($body | ConvertTo-Json -Compress -Depth 5); Headers = $headers
|             TimeoutSec = $timeout; MaxAttempts = $MaxAttempts; AllowStatus = @(400, 403, 404, 409, 413, 422); What = 'Log Analytics query'; AsBytes = $asBytes }
|    if ($readStream) { $rq['ReadStream'] = $readStream }
|    $r = Invoke-SIAzRestRequest @rq
|    if ($readStream -and $r -and $r.PSObject.Properties['Parsed'] -and $null -ne $r.Parsed -and $r.Parsed.PSObject.Properties['SILaStreamFailed']) {
|        # #836: the stream read of this answer failed -- the same query again, read the older way (data first), and said
|        Write-SILaStreamFallback -Reason ('reading this answer as it arrived failed (' + [string]$r.Parsed.SILaStreamFailed + '), so it was read again')
|        $r = $null
|        [void]$rq.Remove('ReadStream')
|        $r = Invoke-SIAzRestRequest @rq
|    }
|    if ($r -and $r.PSObject.Properties['Parsed'] -and $null -ne $r.Parsed -and [int]$r.StatusCode -lt 400) {
|        $streamed = $r.Parsed
|        $r = $null
|        return (Complete-SILaQueryAnswer -Results $streamed.Rows -Columns $streamed.Columns -QueryError $streamed.Error -AllowPartial:$AllowPartial -WorkspaceId $WorkspaceId)
|    }
|    $code = [int]$r.StatusCode
|    # A refusal (always small) is read as text, as is every answer on Windows PowerShell (no System.Text.Json there); an
|    # answer on pwsh 7 is parsed from its bytes below.
|    $content = [string]$r.Content
|    $hasBytes = ($asBytes -and $null -ne $r.Bytes -and $r.Bytes.Length -gt 0)
|    $lean = ($hasBytes -and $code -lt 400 -and $PSVersionTable.PSEdition -eq 'Core')
|    if ($hasBytes -and -not $lean) { $content = [System.Text.Encoding]::UTF8.GetString($r.Bytes) }
|    if ($code -ge 400) { throw (New-SILaQueryRefusedError -Code $code -Content $content -Headers $r.Headers -WorkspaceId $WorkspaceId) }
|    if ($lean) {
|        # a plain statement, never through $( ... ): a subexpression would enumerate the byte array into object[]
|        [byte[]]$answer = $r.Bytes
|        $r = $null
|        $leanAnswer = ConvertFrom-SILaQueryRows -Bytes $answer
|        $answer = $null
|        return (Complete-SILaQueryAnswer -Results $leanAnswer.Rows -Columns $leanAnswer.Columns -QueryError $leanAnswer.Error -AllowPartial:$AllowPartial -WorkspaceId $WorkspaceId)
|    }
|    $parsed = ConvertFrom-SILaQueryJson -Json $content
|    $content = $null
|    $results = [System.Collections.Generic.List[object]]::new()
|    $first = @($parsed.Tables | Where-Object { $_.Name -eq 'PrimaryResult' }) + @($parsed.Tables) | Select-Object -First 1
|    $cols = @()
|    if ($first) {
|        $names = @($first.Columns | ForEach-Object { [string]$_.name })
|        $cols = @($first.Columns | ForEach-Object { [pscustomobject]@{ name = [string]$_.name; type = $(if ($_.PSObject.Properties['type']) { [string]$_.type } else { $null }) } })
|        foreach ($row in $first.Rows) {
|            $o = [ordered]@{}
|            for ($i = 0; $i -lt $names.Count; $i++) { $o[$names[$i]] = $row[$i] }
|            [void]$results.Add([pscustomobject]$o)
|        }
|    }
|    $err = $parsed.Error
|    $parsed = $null; $first = $null
|    return (Complete-SILaQueryAnswer -Results $results.ToArray() -Columns $cols -QueryError $err -AllowPartial:$AllowPartial -WorkspaceId $WorkspaceId)
|}
|
|function New-SILaQueryRefusedError {
|    <# The error a refused query (HTTP 4xx) becomes: the service's own code and message, the body for SI-KqlError. #>
|    param([int]$Code, [AllowNull()][AllowEmptyString()][string]$Content, $Headers, [string]$WorkspaceId = '')
|    $base = "Operation returned an invalid status code '{0}'" -f (Get-SIAzRestStatusName $Code)
|    $resp = [pscustomobject]@{ StatusCode = $Code; Content = $Content; Headers = $Headers }
|    $probe = New-SIAzRestError -Message $base -Response $resp
|    $msg = Get-SIKqlErrorSummary -ErrorRecord $probe
|    if ($msg -eq $base) {
|        # no innererror chain: the top-level error code + message
|        try { $e = ($Content | ConvertFrom-Json).error; if ($e) { $msg = ('{0} -- {1}: {2}' -f $base, [string]$e.code, [string]$e.message) } } catch { }
|    }
|    $ex = New-SIAzRestError -Message $msg -Response $resp
|    $er = New-Object System.Management.Automation.ErrorRecord($ex, 'SILaQueryFailed', [System.Management.Automation.ErrorCategory]::InvalidOperation, $WorkspaceId)
|    $er.ErrorDetails = New-Object System.Management.Automation.ErrorDetails($Content)
|    $er
|}
|
|function Complete-SILaQueryAnswer {
|    <#
|        The end of every Invoke-SILaQuery read: a cut answer (Test-SILaAnswerWhole) THROWS (New-SILaCutAnswerError) unless
|        -AllowPartial; otherwise the answer (New-SILaQueryAnswer), with .Partial = the kind of a partial answer handed out
|        under -AllowPartial ('' when whole).
|    #>
|    param([AllowNull()][AllowEmptyCollection()][object[]]$Results = @(), [AllowNull()][AllowEmptyCollection()][object[]]$Columns = @(), $QueryError,
|          [switch]$AllowPartial, [string]$WorkspaceId = '', [long]$RowCount = -1)
|    $n = $RowCount
|    if ($n -lt 0) { $n = 0L; if ($null -ne $Results) { $n = [long]$Results.Count } }
|    $v = Test-SILaAnswerWhole -ErrorObject $QueryError -Rows $n
|    if (-not $v.Whole -and -not $AllowPartial) { throw (New-SILaCutAnswerError -Verdict $v -ErrorObject $QueryError -WorkspaceId $WorkspaceId) }
|    $a = New-SILaQueryAnswer -Results $Results -Columns $Columns -QueryError $QueryError
|    $kind = ''; if (-not $v.Whole) { $kind = [string]$v.Kind }
|    $a | Add-Member -NotePropertyName Partial -NotePropertyValue $kind -Force
|    $a | Add-Member -NotePropertyName RowCount -NotePropertyValue $n -Force
|    $a
|}
|
|function Invoke-SILaQueryPaged {
|    <#
|        Invoke-SILaQuery -OnPage: the rows handed on a page at a time, never collected (see Invoke-SILaQuery). The streaming
|        reader (SI-LaStreamRead.ps1) delivers each page as soon as about -PageBytes of the answer's own bytes are in; the
|        compact rows of $global:SI_LaCompactRows apply. A cut answer is refused at the end, after the pages (they are
|        provisional until this returns). A stream read that fails BEFORE any page was handed on is read again the older way;
|        one that fails AFTER a page was handed on throws (handing the pages on again would hand some rows twice).
|        Without the streaming reader: the older read, then the rows in pages of the same measured size.
|        Returns the answer shape with no rows in .Results; .RowCount = the rows handed on, .Pages = the pages.
|    #>
|    param([Parameter(Mandatory)][string]$WorkspaceId, [Parameter(Mandatory)][string]$Query, [int]$Wait = 0,
|          [timespan]$Timespan = [timespan]::Zero, [int]$MaxAttempts = 4, [switch]$AllowPartial,
|          [Parameter(Mandatory)][scriptblock]$OnPage, [long]$PageBytes = 4MB)
|    if ($PageBytes -lt 1KB) { $PageBytes = 1KB }
|    $uri = 'https://api.loganalytics.io/v1/workspaces/{0}/query' -f $WorkspaceId.Trim()
|    $body = [ordered]@{ query = $Query }
|    if ($Timespan -gt [timespan]::Zero) { $body['timespan'] = [System.Xml.XmlConvert]::ToString($Timespan) }
|    $headers = @{}
|    $timeout = 300
|    # #882 (A4): Log Analytics stops a query at 3 minutes unless asked to wait -- every query asks for its maximum (10 minutes)
|    if ($Wait -le 0) { $Wait = 600 }
|    if ($Wait -gt 0) { $headers['Prefer'] = ('wait={0}' -f $Wait); $timeout = $Wait + 60 }
|    $rq = @{ Method = 'POST'; Uri = $uri; Audience = 'LaQuery'; Body = ($body | ConvertTo-Json -Compress -Depth 5); Headers = $headers
|             TimeoutSec = $timeout; MaxAttempts = $MaxAttempts; AllowStatus = @(400, 403, 404, 409, 413, 422); What = 'Log Analytics query'
|             AsBytes = ($PSVersionTable.PSEdition -eq 'Core') }
|    $streamable = ($PSVersionTable.PSEdition -eq 'Core' -and (Get-Command -Name Get-SILaStreamReaderType -ErrorAction Ignore) -and (Get-SILaStreamReaderType))
|    $state = @{ Pages = 0; Rows = 0L }
|    if ($streamable) {
|        $__lpCompact = [bool]$global:SI_LaCompactRows
|        $__lpOn = $OnPage; $__lpBytes = $PageBytes; $__lpState = $state
|        $rq['ReadStream'] = { param($s) Read-SILaQueryStreamSafe -Stream $s -Compact:$__lpCompact -OnPage $__lpOn -PageBytes $__lpBytes -PageState $__lpState }
|    } elseif ($PSVersionTable.PSEdition -eq 'Core') {
|        Write-SILaStreamFallback -Once -Reason ([string]$global:SI_LaStreamReaderOff)
|    }
|    $r = Invoke-SIAzRestRequest @rq
|    if ($r -and $r.PSObject.Properties['Parsed'] -and $null -ne $r.Parsed -and $r.Parsed.PSObject.Properties['SILaStreamFailed']) {
|        if ([int]$state.Pages -gt 0) {
|            throw ('Log Analytics: the answer could not be read to its end ({0}) after {1} page(s) had been handed on -- the read is not whole and its pages must not be used' -f [string]$r.Parsed.SILaStreamFailed, $state.Pages)
|        }
|        Write-SILaStreamFallback -Reason ('reading this answer as it arrived failed (' + [string]$r.Parsed.SILaStreamFailed + '), so it was read again')
|        $r = $null
|        [void]$rq.Remove('ReadStream')
|        $r = Invoke-SIAzRestRequest @rq
|    }
|    if ($r -and $r.PSObject.Properties['Parsed'] -and $null -ne $r.Parsed -and [int]$r.StatusCode -lt 400) {
|        $p = $r.Parsed; $r = $null
|        $a = Complete-SILaQueryAnswer -Results @() -Columns $p.Columns -QueryError $p.Error -AllowPartial:$AllowPartial -WorkspaceId $WorkspaceId -RowCount ([long]$p.RowCount)
|        $a | Add-Member -NotePropertyName Pages -NotePropertyValue ([int]$p.Pages) -Force
|        return $a
|    }
|    # the older read (no streaming reader, or read again): the same refusal of a 4xx and of a cut answer, then the pages
|    [void]$rq.Remove('ReadStream')
|    if ($null -eq $r) { $r = Invoke-SIAzRestRequest @rq }
|    $code = [int]$r.StatusCode
|    $content = [string]$r.Content
|    if ($null -ne $r.Bytes -and $r.Bytes.Length -gt 0 -and ($code -ge 400 -or $PSVersionTable.PSEdition -ne 'Core')) { $content = [System.Text.Encoding]::UTF8.GetString($r.Bytes) }
|    if ($code -ge 400) { throw (New-SILaQueryRefusedError -Code $code -Content $content -Headers $r.Headers -WorkspaceId $WorkspaceId) }
|    $lean = $null
|    if ($null -ne $r.Bytes -and $r.Bytes.Length -gt 0 -and $PSVersionTable.PSEdition -eq 'Core') {
|        [byte[]]$bytes = $r.Bytes
|        $total = [long]$bytes.Length
|        $r = $null
|        $lean = ConvertFrom-SILaQueryRows -Bytes $bytes
|        $bytes = $null
|    } else {
|        $total = [long][System.Text.Encoding]::UTF8.GetByteCount($content)
|        $parsed = ConvertFrom-SILaQueryJson -Json $content
|        $content = $null
|        $first = @($parsed.Tables | Where-Object { $_.Name -eq 'PrimaryResult' }) + @($parsed.Tables) | Select-Object -First 1
|        $rowsL = [System.Collections.Generic.List[object]]::new(); $colsL = @()
|        if ($first) {
|            $names = @($first.Columns | ForEach-Object { [string]$_.name })
|            $colsL = @($first.Columns | ForEach-Object { [pscustomobject]@{ name = [string]$_.name; type = $(if ($_.PSObject.Properties['type']) { [string]$_.type } else { $null }) } })
|            foreach ($row in $first.Rows) { $o = [ordered]@{}; for ($i = 0; $i -lt $names.Count; $i++) { $o[$names[$i]] = $row[$i] }; [void]$rowsL.Add([pscustomobject]$o) }
|        }
|        $lean = [pscustomobject]@{ Rows = $rowsL.ToArray(); Columns = $colsL; Error = $parsed.Error }
|        $parsed = $null; $first = $null
|    }
|    $all = @($lean.Rows); $n = $all.Count
|    # a cut answer is refused BEFORE a page is handed on (the whole answer is in hand on this path)
|    $v = Test-SILaAnswerWhole -ErrorObject $lean.Error -Rows $n
|    if (-not $v.Whole -and -not $AllowPartial) { throw (New-SILaCutAnswerError -Verdict $v -ErrorObject $lean.Error -WorkspaceId $WorkspaceId) }
|    # pages of about -PageBytes of the answer: the measured bytes per row of this answer decide the rows per page
|    $per = $n
|    if ($n -gt 0 -and $total -gt $PageBytes) { $per = [int][Math]::Max(1, [Math]::Floor($n * ([double]$PageBytes / [double]$total))) }
|    $pages = 0
|    for ($i = 0; $i -lt $n; $i += [Math]::Max(1, $per)) {
|        $len = [Math]::Min([Math]::Max(1, $per), $n - $i)
|        $pg = [object[]]::new($len); [Array]::Copy($all, $i, $pg, 0, $len)
|        $null = & $OnPage $pg
|        $pages++
|        for ($k = $i; $k -lt $i + $len; $k++) { $all[$k] = $null }
|    }
|    $a = Complete-SILaQueryAnswer -Results @() -Columns $lean.Columns -QueryError $lean.Error -AllowPartial:$AllowPartial -WorkspaceId $WorkspaceId -RowCount ([long]$n)
|    $a | Add-Member -NotePropertyName Pages -NotePropertyValue $pages -Force
|    $a
|}
|
|function New-SILaQueryAnswer {
|    <#
|        PURE. The one shape Invoke-SILaQuery answers (#639): .Results (the rows), .Columns (name / type), .Tables = the
|        primary table's SCHEMA only (Name, Columns, no rows -- RowsOmitted), .Error. The rows are never held twice.
|    #>
|    param([AllowNull()][AllowEmptyCollection()][object[]]$Results = @(), [AllowNull()][AllowEmptyCollection()][object[]]$Columns = @(), $QueryError)
|    $c = @($Columns | Where-Object { $null -ne $_ })
|    $schema = [pscustomobject]@{ Name = 'PrimaryResult'; Columns = $c; Rows = @(); RowsOmitted = $true }
|    # plain statements: an if used as a value would unroll the rows (one row would come back as that row, not a list)
|    $rows = $Results
|    if ($null -eq $rows) { $rows = [object[]]@() }
|    [pscustomobject]@{ Results = $rows; Columns = $c; Tables = @($schema); Error = $QueryError; Statistics = $null; Render = $null }
|}
|
|# =====================================================================================================================
|#  Storage data plane: blob, queue, table (OAuth bearer, x-ms-version)
|# =====================================================================================================================
|
|function Get-SIStorageApiVersion { '2021-08-06' }
|
|function Get-SIStorageUri {
|    param([Parameter(Mandatory)][string]$Account, [ValidateSet('blob', 'queue', 'table')][string]$Service = 'blob', [string]$Path = '', [string]$Query = '')
|    $p = (($Path -split '/') | ForEach-Object { [uri]::EscapeDataString($_) }) -join '/'
|    $u = 'https://{0}.{1}.core.windows.net/{2}' -f $Account, $Service, $p
|    if ($Query) { $u += '?' + $Query }
|    return $u
|}
|
|function Invoke-SIStorageRequest {
|    param([string]$Method = 'GET', [Parameter(Mandatory)][string]$Uri, $Body, [string]$ContentType, [hashtable]$Headers, [switch]$AllowNotFound, [int[]]$AllowStatus = @(), [switch]$AsBytes, [string]$What = 'Azure Storage request')
|    $h = @{ 'x-ms-version' = (Get-SIStorageApiVersion); 'x-ms-date' = [datetime]::UtcNow.ToString('R') }
|    if ($Headers) { foreach ($k in $Headers.Keys) { $h[$k] = $Headers[$k] } }
|    if (-not $ContentType) { $ContentType = 'application/octet-stream' }
|    return (Invoke-SIAzRestRequest -Method $Method -Uri $Uri -Audience Storage -Body $Body -ContentType $ContentType -Headers $h -AllowNotFound:$AllowNotFound -AllowStatus $AllowStatus -AsBytes:$AsBytes -What $What)
|}
|
|function ConvertTo-SIStorageDate {
|    param([string]$Text)
|    $d = [DateTimeOffset]::MinValue
|    if ($Text -and [DateTimeOffset]::TryParse($Text, [System.Globalization.CultureInfo]::InvariantCulture, [System.Globalization.DateTimeStyles]::AssumeUniversal, [ref]$d)) { return $d }
|    return $null
|}
|
|function Get-SIBlobProperties {
|    <# HEAD of one blob: @{ Name; Length; LastModified; ETag; ContentType } or $null when it does not exist. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container, [Parameter(Mandatory)][string]$Blob)
|    $r = Invoke-SIStorageRequest -Method HEAD -Uri (Get-SIStorageUri -Account $Account -Path ("$Container/$Blob")) -AllowNotFound -What ("Blob '{0}/{1}'" -f $Container, $Blob)
|    if (-not $r) { return $null }
|    $len = 0L; [void][long]::TryParse([string]$r.Headers['Content-Length'], [ref]$len)
|    return [pscustomobject]@{ Name = $Blob; Container = $Container; Length = $len; LastModified = (ConvertTo-SIStorageDate $r.Headers['Last-Modified']); ETag = [string]$r.Headers['ETag']; ContentType = [string]$r.Headers['Content-Type'] }
|}
|
|function Get-SIBlobList {
|    <# Every blob in -Container under -Prefix (List Blobs, following the marker). #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container, [string]$Prefix)
|    $out = [System.Collections.Generic.List[object]]::new()
|    $marker = $null
|    do {
|        $q = 'restype=container&comp=list&maxresults=5000'
|        if ($Prefix) { $q += '&prefix=' + [uri]::EscapeDataString($Prefix) }
|        if ($marker) { $q += '&marker=' + [uri]::EscapeDataString($marker) }
|        $r = Invoke-SIStorageRequest -Method GET -Uri (Get-SIStorageUri -Account $Account -Path $Container -Query $q) -Headers @{ Accept = 'application/xml' } -What ("List blobs in '{0}'" -f $Container)
|        # The listing is XML (EnumerationResults). A cast `[xml]$text` that fails puts the WHOLE listing (up to 5,000 blobs)
|        # into its error text -- customer B 2026-10-15: "Cannot convert value "<?xml ... EnumerationResults ..." to type
|        # System.Xml.XmlDocument. Error: OutOfMemoryException" as the run's end text. Parsed here; a failure says what failed
|        # and why, in one short line, never the payload.
|        $x = New-Object System.Xml.XmlDocument
|        try { $x.LoadXml((([string]$r.Content) -replace '^\uFEFF', '')) }
|        catch {
|            $why = $_.Exception.Message; if ($_.Exception.InnerException) { $why = $_.Exception.InnerException.Message }
|            if ($why.Length -gt 300) { $why = $why.Substring(0, 300) }
|            throw ("The blob list of '{0}' (prefix '{1}') could not be read: {2}" -f $Container, $Prefix, $why)
|        }
|        foreach ($b in @($x.EnumerationResults.Blobs.Blob)) {
|            if ($null -eq $b) { continue }
|            $len = 0L; [void][long]::TryParse([string]$b.Properties.'Content-Length', [ref]$len)
|            [void]$out.Add([pscustomobject]@{ Name = [string]$b.Name; Container = $Container; Length = $len; LastModified = (ConvertTo-SIStorageDate ([string]$b.Properties.'Last-Modified')); ETag = [string]$b.Properties.Etag; ContentType = [string]$b.Properties.'Content-Type' })
|        }
|        $marker = [string]$x.EnumerationResults.NextMarker
|    } while ($marker)
|    return $out.ToArray()
|}
|
|function Get-SIBlobContent {
|    <# Download one blob: the bytes, or -Destination writes them to a file (returns the path). -AllowMissing: a blob that
|       does not exist (404) returns $null -- no error is raised or logged (2026-10-23: the pipeline's poll of a run's
|       records marker logged a TerminatingError 404 every 30 s, hiding the real errors). #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container, [Parameter(Mandatory)][string]$Blob, [string]$Destination, [switch]$AllowMissing)
|    $r = Invoke-SIStorageRequest -Method GET -Uri (Get-SIStorageUri -Account $Account -Path ("$Container/$Blob")) -AsBytes -AllowNotFound:$AllowMissing -What ("Download blob '{0}/{1}'" -f $Container, $Blob)
|    if ($AllowMissing -and $null -eq $r) { return $null }
|    # PLAIN statements, never `$bytes = if (...) { [byte[]]... }`: an `if` used as a value sends the array through the
|    # pipeline ONE BYTE AT A TIME into an object[] -- about 30 times the blob's size in memory. A new customer install
|    # 2026-10-12: the Azure collection's 13,562 assets made one large part, and reading it back ended in
|    # "System.OutOfMemoryException" on a job with 4 GiB and again with 8 GiB.
|    $bytes = $r.Bytes
|    if ($null -eq $bytes) { $bytes = [byte[]]::new(0) }
|    if (-not $Destination) { return ,$bytes }
|    [System.IO.File]::WriteAllBytes($Destination, $bytes)
|    return $Destination
|}
|
|function Set-SIBlobContent {
|    <# Upload one block blob (create or overwrite) from -File or -Bytes. -IfMatchETag makes it conditional (412 when
|       another writer got there first); -IfNoneMatch creates it only when it does not exist yet (409 / 412 when it does --
|       a claim exactly one writer wins). Returns the new ETag. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container, [Parameter(Mandatory)][string]$Blob,
|          [string]$File, [byte[]]$Bytes, [string]$IfMatchETag, [string]$ContentType = 'application/octet-stream', [switch]$IfNoneMatch)
|    if ($File) { $Bytes = [System.IO.File]::ReadAllBytes($File) }
|    if ($null -eq $Bytes) { $Bytes = [byte[]]@() }
|    $h = @{ 'x-ms-blob-type' = 'BlockBlob' }
|    if ($IfMatchETag) { $h['If-Match'] = $IfMatchETag }
|    if ($IfNoneMatch) { $h['If-None-Match'] = '*' }
|    $r = Invoke-SIStorageRequest -Method PUT -Uri (Get-SIStorageUri -Account $Account -Path ("$Container/$Blob")) -Body $Bytes -ContentType $ContentType -Headers $h -What ("Upload blob '{0}/{1}'" -f $Container, $Blob)
|    return [string]$r.Headers['ETag']
|}
|
|function Remove-SIBlob {
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container, [Parameter(Mandatory)][string]$Blob)
|    $null = Invoke-SIStorageRequest -Method DELETE -Uri (Get-SIStorageUri -Account $Account -Path ("$Container/$Blob")) -AllowNotFound -What ("Delete blob '{0}/{1}'" -f $Container, $Blob)
|}
|
|function Test-SIBlobContainer {
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container)
|    $r = Invoke-SIStorageRequest -Method HEAD -Uri (Get-SIStorageUri -Account $Account -Path $Container -Query 'restype=container') -AllowNotFound -What ("Container '{0}'" -f $Container)
|    if (-not $r) { return $null }
|    return [pscustomobject]@{ Name = $Container; LastModified = (ConvertTo-SIStorageDate $r.Headers['Last-Modified']); ETag = [string]$r.Headers['ETag'] }
|}
|
|function New-SIBlobContainer {
|    <# Create a private container; an existing one is not an error. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Container)
|    $null = Invoke-SIStorageRequest -Method PUT -Uri (Get-SIStorageUri -Account $Account -Path $Container -Query 'restype=container') -AllowStatus @(409) -What ("Create container '{0}'" -f $Container)
|    return [pscustomobject]@{ Name = $Container }
|}
|
|function Test-SIQueue {
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue)
|    $r = Invoke-SIStorageRequest -Method GET -Uri (Get-SIStorageUri -Account $Account -Service queue -Path $Queue -Query 'comp=metadata') -AllowNotFound -What ("Queue '{0}'" -f $Queue)
|    return [bool]$r
|}
|
|function New-SIQueue {
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue)
|    $null = Invoke-SIStorageRequest -Method PUT -Uri (Get-SIStorageUri -Account $Account -Service queue -Path $Queue) -AllowStatus @(409) -What ("Create queue '{0}'" -f $Queue)
|}
|
|function Send-SIQueueMessage {
|    <# Put one message. The text is sent as-is (XML-escaped), the encoding the Az.Storage 9 queue client uses. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue, [Parameter(Mandatory)][AllowEmptyString()][string]$Text)
|    $body = '<QueueMessage><MessageText>{0}</MessageText></QueueMessage>' -f [System.Security.SecurityElement]::Escape($Text)
|    $r = Invoke-SIStorageRequest -Method POST -Uri (Get-SIStorageUri -Account $Account -Service queue -Path ("$Queue/messages")) -Body $body -ContentType 'application/xml' -What ("Send to queue '{0}'" -f $Queue)
|    $x = [xml]($r.Content -replace '^\uFEFF', '')
|    return [pscustomobject]@{ MessageId = [string]$x.QueueMessagesList.QueueMessage.MessageId; PopReceipt = [string]$x.QueueMessagesList.QueueMessage.PopReceipt }
|}
|
|function Receive-SIQueueMessage {
|    <# Lease one message for -VisibilityTimeoutSeconds: @{ MessageId; PopReceipt; MessageText; DequeueCount } or $null
|       when the queue is empty. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue, [int]$VisibilityTimeoutSeconds = 30)
|    $q = 'numofmessages=1&visibilitytimeout={0}' -f $VisibilityTimeoutSeconds
|    $r = Invoke-SIStorageRequest -Method GET -Uri (Get-SIStorageUri -Account $Account -Service queue -Path ("$Queue/messages") -Query $q) -Headers @{ Accept = 'application/xml' } -What ("Receive from queue '{0}'" -f $Queue)
|    $x = [xml]($r.Content -replace '^\uFEFF', '')
|    $m = @($x.QueueMessagesList.QueueMessage) | Where-Object { $_ } | Select-Object -First 1
|    if (-not $m) { return $null }
|    return [pscustomobject]@{ MessageId = [string]$m.MessageId; PopReceipt = [string]$m.PopReceipt; MessageText = [string]$m.MessageText; DequeueCount = [int]$m.DequeueCount }
|}
|
|function Update-SIQueueMessage {
|    <#
|        RENEW the hold on one leased message: its visibility timeout is set to -VisibilityTimeoutSeconds from now (Update
|        Message). The message text goes back unchanged (-Text: as it was received). NEVER THROWS -- the answer says which:
|          @{ Ok = $true;  PopReceipt = <the NEW receipt: the old one is no longer valid> }
|          @{ Ok = $false; Lost = $true;  Why }   the message is gone (404) or another worker holds it (400 PopReceiptMismatch)
|          @{ Ok = $false; Lost = $false; Why }   anything else (network, sign-in, a 5xx): not known -- try again
|        Short timeouts and two attempts: this is called from a heartbeat, which must not hang on one request.
|        -Auth: the identity to sign in as (a second thread has no sign-in of its own; Resolve-SIAzRestAuth's answer).
|    #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue, [Parameter(Mandatory)][string]$MessageId, [Parameter(Mandatory)][string]$PopReceipt,
|          [Parameter(Mandatory)][int]$VisibilityTimeoutSeconds, [AllowEmptyString()][string]$Text = '', [hashtable]$Auth, [int]$TimeoutSec = 30)
|    try {
|        $q = 'popreceipt={0}&visibilitytimeout={1}' -f [uri]::EscapeDataString($PopReceipt), $VisibilityTimeoutSeconds
|        $body = '<QueueMessage><MessageText>{0}</MessageText></QueueMessage>' -f [System.Security.SecurityElement]::Escape($Text)
|        $h = @{ 'x-ms-version' = (Get-SIStorageApiVersion); 'x-ms-date' = [datetime]::UtcNow.ToString('R') }
|        $r = Invoke-SIAzRestRequest -Method PUT -Uri (Get-SIStorageUri -Account $Account -Service queue -Path ("$Queue/messages/$MessageId") -Query $q) -Audience Storage -Body $body `
|                -ContentType 'application/xml' -Headers $h -AllowStatus @(400, 404) -TimeoutSec $TimeoutSec -MaxAttempts 2 -Auth $Auth -What ("Renew the hold on a message of queue '{0}'" -f $Queue)
|        $code = 0; try { $code = [int]$r.StatusCode } catch { }
|        if ($code -ge 200 -and $code -lt 300) {
|            $new = [string]$r.Headers['x-ms-popreceipt']
|            if (-not $new) { return [pscustomobject]@{ Ok = $false; Lost = $false; PopReceipt = $PopReceipt; Why = 'the queue answered without a new receipt' } }
|            return [pscustomobject]@{ Ok = $true; Lost = $false; PopReceipt = $new; Why = '' }
|        }
|        if ($code -eq 404) { return [pscustomobject]@{ Ok = $false; Lost = $true; PopReceipt = $PopReceipt; Why = 'the message is no longer in the queue' } }
|        $said = [string]$r.Content; try { if ($r.Headers -and $r.Headers['x-ms-error-code']) { $said += ' ' + [string]$r.Headers['x-ms-error-code'] } } catch { }
|        if ($code -eq 400 -and $said -match '(?i)PopReceiptMismatch|MessageNotFound') { return [pscustomobject]@{ Ok = $false; Lost = $true; PopReceipt = $PopReceipt; Why = 'another worker holds the message now' } }
|        return [pscustomobject]@{ Ok = $false; Lost = $false; PopReceipt = $PopReceipt; Why = ('HTTP {0}: {1}' -f $code, (([string]$r.Content -replace '\s+', ' ').Trim() -replace '^(.{200}).*$', '$1...')) }
|    } catch {
|        return [pscustomobject]@{ Ok = $false; Lost = $false; PopReceipt = $PopReceipt; Why = [string]$_.Exception.Message }
|    }
|}
|
|function Remove-SIQueueMessage {
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Queue, [Parameter(Mandatory)][string]$MessageId, [Parameter(Mandatory)][string]$PopReceipt)
|    $q = 'popreceipt=' + [uri]::EscapeDataString($PopReceipt)
|    $null = Invoke-SIStorageRequest -Method DELETE -Uri (Get-SIStorageUri -Account $Account -Service queue -Path ("$Queue/messages/$MessageId") -Query $q) -AllowNotFound -What ("Delete from queue '{0}'" -f $Queue)
|}
|
|function Get-SITableEntity {
|    <# One table entity (PartitionKey + RowKey) or $null; without -RowKey, every entity of the partition (following the
|       continuation headers). #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Table, [Parameter(Mandatory)][string]$PartitionKey, [string]$RowKey)
|    $h = @{ Accept = 'application/json;odata=nometadata' }
|    $esc = { param($s) ([string]$s).Replace("'", "''") }
|    if ($RowKey) {
|        $path = "{0}(PartitionKey='{1}',RowKey='{2}')" -f $Table, [uri]::EscapeDataString((& $esc $PartitionKey)), [uri]::EscapeDataString((& $esc $RowKey))
|        $r = Invoke-SIStorageRequest -Method GET -Uri ('https://{0}.table.core.windows.net/{1}' -f $Account, $path) -Headers $h -ContentType 'application/json' -AllowNotFound -What ("Table '{0}' entity" -f $Table)
|        if (-not $r) { return $null }
|        return ($r.Content | ConvertFrom-Json)
|    }
|    $out = [System.Collections.Generic.List[object]]::new()
|    $filter = [uri]::EscapeDataString(("PartitionKey eq '{0}'" -f (& $esc $PartitionKey)))
|    $np = $null; $nr = $null
|    do {
|        $q = '$filter=' + $filter
|        if ($np) { $q += '&NextPartitionKey=' + [uri]::EscapeDataString($np) }
|        if ($nr) { $q += '&NextRowKey=' + [uri]::EscapeDataString($nr) }
|        $r = Invoke-SIStorageRequest -Method GET -Uri ('https://{0}.table.core.windows.net/{1}()?{2}' -f $Account, $Table, $q) -Headers $h -ContentType 'application/json' -What ("Table '{0}' query" -f $Table)
|        foreach ($e in @(($r.Content | ConvertFrom-Json).value)) { if ($e) { [void]$out.Add($e) } }
|        $np = [string]$r.Headers['x-ms-continuation-NextPartitionKey']; $nr = [string]$r.Headers['x-ms-continuation-NextRowKey']
|    } while ($np)
|    return $out.ToArray()
|}
|
|function Set-SITableEntity {
|    <# UPSERT one entity (Insert Or Replace; -Merge = Insert Or Merge). -Entity is a hashtable of properties. #>
|    param([Parameter(Mandatory)][string]$Account, [Parameter(Mandatory)][string]$Table, [Parameter(Mandatory)][string]$PartitionKey,
|          [Parameter(Mandatory)][string]$RowKey, [hashtable]$Entity = @{}, [switch]$Merge)
|    $e = [ordered]@{ PartitionKey = $PartitionKey; RowKey = $RowKey }
|    foreach ($k in $Entity.Keys) { if ($k -notin 'PartitionKey', 'RowKey') { $e[$k] = $Entity[$k] } }
|    $esc = { param($s) ([string]$s).Replace("'", "''") }
|    $path = "{0}(PartitionKey='{1}',RowKey='{2}')" -f $Table, [uri]::EscapeDataString((& $esc $PartitionKey)), [uri]::EscapeDataString((& $esc $RowKey))
|    $bytes = [System.Text.Encoding]::UTF8.GetBytes(($e | ConvertTo-Json -Depth 5 -Compress))
|    $null = Invoke-SIStorageRequest -Method $(if ($Merge) { 'MERGE' } else { 'PUT' }) -Uri ('https://{0}.table.core.windows.net/{1}' -f $Account, $path) -Body $bytes `
|                -ContentType 'application/json' -Headers @{ Accept = 'application/json;odata=nometadata' } -What ("Table '{0}' upsert" -f $Table)
|}
|
|# =====================================================================================================================
|#  The wrappers -- each forwards to its REST twin below
|# =====================================================================================================================
|# Each declares the parameters SecurityInsight's call sites use, UNTYPED except switches, and forwards @PSBoundParameters
|# -- never @args (measured: @args splits -Name:$value into a switch plus a positional value).
|function Connect-SIAzAccount {
|    [CmdletBinding()]
|    param([switch]$Identity, $AccountId, [switch]$ServicePrincipal, $ApplicationId, $CertificateThumbprint,
|          $CertificatePath, $CertificatePassword, $Credential,
|          [Alias('TenantId')]$Tenant, [Alias('SubscriptionId')]$Subscription, $Scope)
|    return (Connect-SIAzAccountRest @PSBoundParameters)
|}
|function Disconnect-SIAzAccount {
|    [CmdletBinding()] param($Scope)
|    return (Disconnect-SIAzAccountRest @PSBoundParameters)
|}
|function Disable-SIAzContextAutosave {
|    [CmdletBinding()] param($Scope)
|    return (Disable-SIAzContextAutosaveRest @PSBoundParameters)
|}
|function Get-SIAzContext {
|    [CmdletBinding()] param()
|    return (Get-SIAzContextRest @PSBoundParameters)
|}
|function Set-SIAzContext {
|    [CmdletBinding()]
|    param([Alias('SubscriptionId', 'SubscriptionName')]$Subscription, [Alias('TenantId', 'Domain')]$Tenant, $Context, $Scope)
|    return (Set-SIAzContextRest @PSBoundParameters)
|}
|function Get-SIAzAccessToken {
|    [CmdletBinding()] param($ResourceUrl, $TenantId)
|    return (Get-SIAzAccessTokenRest @PSBoundParameters)
|}
|function Get-SIAzSubscription {
|    [CmdletBinding()] param($TenantId, $SubscriptionId)
|    return (Get-SIAzSubscriptionRest @PSBoundParameters)
|}
|function Invoke-SIAzRestMethod {
|    [CmdletBinding()] param($Path, $Method, $Payload)
|    return (Invoke-SIAzRestMethodRest @PSBoundParameters)
|}
|function Invoke-SIAzOperationalInsightsQuery {
|    # -AllowPartial: the caller reads .Error itself (Invoke-SILaQuery refuses a cut answer otherwise); -OnPage / -PageBytes:
|    # the rows a page at a time (Invoke-SILaQuery)
|    [CmdletBinding()] param($WorkspaceId, $Query, $Wait, $Timespan, [switch]$AllowPartial, [scriptblock]$OnPage, [long]$PageBytes)
|    return (Invoke-SIAzOperationalInsightsQueryRest @PSBoundParameters)
|}
|function Get-SIAzOperationalInsightsWorkspace {
|    [CmdletBinding()] param($ResourceGroupName, $Name)
|    return (Get-SIAzOperationalInsightsWorkspaceRest @PSBoundParameters)
|}
|function New-SIAzOperationalInsightsWorkspace {
|    [CmdletBinding()] param($ResourceGroupName, $Name, $Location, $Sku, $RetentionInDays)
|    return (New-SIAzOperationalInsightsWorkspaceRest @PSBoundParameters)
|}
|function Search-SIAzGraph {
|    [CmdletBinding()] param($Query, $First, $Skip, $Subscription, $ManagementGroup, $SkipToken)
|    return ,(Search-SIAzGraphRest @PSBoundParameters)   # one page object, not its rows
|}
|function Get-SIAzKeyVaultSecret {
|    [CmdletBinding()] param($VaultName, $Name, [switch]$AsPlainText)
|    return (Get-SIAzKeyVaultSecretRest @PSBoundParameters)
|}
|function Set-SIAzKeyVaultSecret {
|    [CmdletBinding()] param($VaultName, $Name, $SecretValue, $ContentType)
|    return (Set-SIAzKeyVaultSecretRest @PSBoundParameters)
|}
|function Get-SIAzResourceGroup {
|    [CmdletBinding()] param($Name)
|    return (Get-SIAzResourceGroupRest @PSBoundParameters)
|}
|function New-SIAzResourceGroup {
|    [CmdletBinding()] param($Name, $Location, $Tag)
|    return (New-SIAzResourceGroupRest @PSBoundParameters)
|}
|function Get-SIAzRoleAssignment {
|    [CmdletBinding()] param($ObjectId, $Scope, $RoleDefinitionName)
|    return (Get-SIAzRoleAssignmentRest @PSBoundParameters)
|}
|function New-SIAzRoleAssignment {
|    [CmdletBinding()] param($ObjectId, $Scope, $RoleDefinitionName, $Description)
|    return (New-SIAzRoleAssignmentRest @PSBoundParameters)
|}
|function Get-SIAzRoleDefinition {
|    [CmdletBinding()] param([switch]$Custom, $Name, $Scope)
|    return (Get-SIAzRoleDefinitionRest @PSBoundParameters)
|}
|function Get-SIAzTag {
|    [CmdletBinding()] param($ResourceId)
|    return (Get-SIAzTagRest @PSBoundParameters)
|}
|function Update-SIAzTag {
|    [CmdletBinding()] param($ResourceId, $Tag, $Operation)
|    return (Update-SIAzTagRest @PSBoundParameters)
|}
|function Get-SIAzADServicePrincipal {
|    [CmdletBinding()] param($ApplicationId, $ObjectId)
|    return (Get-SIAzADServicePrincipalRest @PSBoundParameters)
|}
|function Get-SIAzDataCollectionEndpoint {
|    [CmdletBinding()] param($Name, $ResourceGroupName)
|    return (Get-SIAzDataCollectionEndpointRest @PSBoundParameters)
|}
|function New-SIAzDataCollectionEndpoint {
|    [CmdletBinding()] param($Name, $ResourceGroupName, $Location, $NetworkAclsPublicNetworkAccess)
|    return (New-SIAzDataCollectionEndpointRest @PSBoundParameters)
|}
|function Get-SIAzDataCollectionRule {
|    [CmdletBinding()] param($Name, $ResourceGroupName)
|    return (Get-SIAzDataCollectionRuleRest @PSBoundParameters)
|}
|function New-SIAzStorageContext {
|    [CmdletBinding()] param($StorageAccountName, [switch]$UseConnectedAccount)
|    return (New-SIAzStorageContextRest @PSBoundParameters)
|}
|function Get-SIAzStorageAccount {
|    [CmdletBinding()] param($ResourceGroupName, $Name)
|    return (Get-SIAzStorageAccountRest @PSBoundParameters)
|}
|function New-SIAzStorageAccount {
|    [CmdletBinding()]
|    param($ResourceGroupName, $Name, $Location, $SkuName, $Kind, $EnableHttpsTrafficOnly,
|          $MinimumTlsVersion, $AllowBlobPublicAccess, $PublicNetworkAccess)
|    return (New-SIAzStorageAccountRest @PSBoundParameters)
|}
|function Get-SIAzStorageContainer {
|    [CmdletBinding()] param($Name, $Context)
|    return (Get-SIAzStorageContainerRest @PSBoundParameters)
|}
|function New-SIAzStorageContainer {
|    [CmdletBinding()] param($Name, $Context, $Permission)
|    return (New-SIAzStorageContainerRest @PSBoundParameters)
|}
|function Get-SIAzStorageBlob {
|    [CmdletBinding()] param($Container, $Blob, $Prefix, $Context)
|    return (Get-SIAzStorageBlobRest @PSBoundParameters)
|}
|function Get-SIAzStorageBlobContent {
|    [CmdletBinding()] param($Container, $Blob, $CloudBlob, $Destination, $Context, [switch]$Force)
|    return (Get-SIAzStorageBlobContentRest @PSBoundParameters)
|}
|function Set-SIAzStorageBlobContent {
|    [CmdletBinding()] param($File, $Container, $Blob, $Context, [switch]$Force)
|    return (Set-SIAzStorageBlobContentRest @PSBoundParameters)
|}
|function Remove-SIAzStorageBlob {
|    [CmdletBinding()] param($Container, $Blob, $Context, [switch]$Force)
|    return (Remove-SIAzStorageBlobRest @PSBoundParameters)
|}
|function Start-SIAzStorageBlobCopy {
|    [CmdletBinding()] param($SrcContainer, $SrcBlob, $DestContainer, $DestBlob, $Context, [switch]$Force)
|    return (Start-SIAzStorageBlobCopyRest @PSBoundParameters)
|}
|function Get-SIAzStorageQueue {
|    [CmdletBinding()] param($Name, $Context)
|    return (Get-SIAzStorageQueueRest @PSBoundParameters)
|}
|function New-SIAzStorageQueue {
|    [CmdletBinding()] param($Name, $Context)
|    return (New-SIAzStorageQueueRest @PSBoundParameters)
|}
|
|function Set-SIAzStorageBlobContentIfMatch {
|    <# The ledger's CONDITIONAL write (only when the blob still has -IfMatchETag): PUT with If-Match. A lost race fails
|       with '412 ConditionNotMet'. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$File, [Parameter(Mandatory)][string]$Container, [Parameter(Mandatory)][string]$Blob,
|          [Parameter(Mandatory)][object]$Context, [Parameter(Mandatory)][string]$IfMatchETag)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    $null = Set-SIBlobContent -Account $acct -Container $Container -Blob $Blob -File $File -IfMatchETag $IfMatchETag
|}
|# =====================================================================================================================
|#  The REST twins -- what each wrapper does with no Az module
|# =====================================================================================================================
|
|function Write-SIAzRestNotFound {
|    <# A lookup that found nothing, the way the Az cmdlet reports it: a NON-terminating error, so -ErrorAction
|       SilentlyContinue yields $null and -ErrorAction Stop throws. #>
|    param([Parameter(Mandatory)]$Cmdlet, [Parameter(Mandatory)][string]$Message, [string]$Target)
|    $er = New-Object System.Management.Automation.ErrorRecord((New-Object System.Exception($Message)), 'SIAzRestNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $Target)
|    $Cmdlet.WriteError($er)
|}
|
|function Get-SIAzRestSubscriptionId {
|    <# The current subscription: Set-SIAzContext / Connect -Subscription, else the install's workspace subscription,
|       else the first enabled subscription the identity sees (what Connect-AzAccount selects). #>
|    param([switch]$NoLookup)
|    $st = Get-SIAzRestState
|    if ($st.SubscriptionId) { return [string]$st.SubscriptionId }
|    $s = [string](Get-SIAzRestValue 'SI_AzSubscriptionId')
|    if (-not $s -and [string](Get-SIAzRestValue 'SI_WorkspaceResourceId') -match '/subscriptions/([^/]+)/') { $s = $Matches[1] }
|    if (-not $s) { $s = [string](Get-SIAzRestValue 'SubscriptionId') }
|    # in an Invardia Support session, the first subscription the environment names
|    if (-not $s) { $sess = Get-SISupportSession; if ($sess -and $sess.SubscriptionId) { $s = [string]$sess.SubscriptionId } }
|    if (-not $s -and -not $NoLookup) {
|        try {
|            $first = @(Invoke-SIArm -Path '/subscriptions' -ApiVersion '2022-12-01' -List | Where-Object { [string]$_.state -eq 'Enabled' }) | Select-Object -First 1
|            if ($first) { $s = [string]$first.subscriptionId }
|        } catch { }
|    }
|    if ($s) { $st.SubscriptionId = $s }
|    return $s
|}
|
|function Get-SIAzRestTenantId {
|    $st = Get-SIAzRestState
|    if ($st.TenantId) { return [string]$st.TenantId }
|    $a = Resolve-SIAzRestAuth
|    $t = [string]$a.TenantId
|    if (-not $t) {
|        # a managed identity knows its tenant: read it from its own ARM token
|        try { $c = ConvertFrom-SIJwtPayload (Get-SIAzureToken -Audience Arm); if ($c) { $t = [string]$c.tid } } catch { }
|    }
|    if ($t) { $st.TenantId = $t }
|    return $t
|}
|
|function Connect-SIAzAccountRest {
|    <# RECORDS the identity; no sign-in happens here (each REST call mints its token when it needs one). #>
|    [CmdletBinding()]
|    param([switch]$Identity, [string]$AccountId, [switch]$ServicePrincipal, [string]$ApplicationId, [string]$CertificateThumbprint,
|          [string]$CertificatePath, [securestring]$CertificatePassword, [pscredential]$Credential,
|          [Alias('TenantId')][string]$Tenant, [Alias('SubscriptionId')][string]$Subscription, [string]$Scope)
|    $st = Get-SIAzRestState
|    $conn = $null
|    if ($Identity) {
|        $cid = if ($AccountId) { $AccountId } else { [string](Get-SIAzRestValue 'SI_UAMI_ClientId', 'SI_ManagedIdentityClientId') }
|        $conn = @{ Mode = 'ManagedIdentity'; ClientId = $cid }
|    } elseif ($Credential) {
|        $conn = @{ Mode = 'Secret'; AppId = [string]$Credential.UserName; TenantId = $Tenant; Secret = $Credential.GetNetworkCredential().Password }
|    } elseif ($CertificateThumbprint -or $CertificatePath) {
|        $thumb = $CertificateThumbprint
|        if ($CertificatePath) {
|            # the PFX the container wrote: the token signer looks a certificate up by thumbprint in the X509 store, so
|            # it goes into CurrentUser\My (the only store a Linux container has) unless it is already there
|            $pw = if ($CertificatePassword) { [System.Net.NetworkCredential]::new('', $CertificatePassword).Password } else { '' }
|            $flags = [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable -bor [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::PersistKeySet
|            $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new([System.IO.File]::ReadAllBytes($CertificatePath), $pw, $flags)
|            $thumb = [string]$cert.Thumbprint
|            Initialize-SIAzRestHelpers
|            if (-not (Get-SICertificateFromStore -Thumbprint $thumb)) {
|                $store = New-Object System.Security.Cryptography.X509Certificates.X509Store('My', 'CurrentUser')
|                try { $store.Open('ReadWrite'); $store.Add($cert) } finally { $store.Close() }
|            }
|        }
|        $conn = @{ Mode = 'Certificate'; AppId = $ApplicationId; TenantId = $Tenant; Thumbprint = ($thumb -replace '\s', '') }
|    } else {
|        throw 'Connect-SIAzAccount (REST): name the identity -- -Identity, -Credential, or -ApplicationId with -CertificateThumbprint / -CertificatePath.'
|    }
|    $st.Connection = $conn
|    $st.TenantId = if ($Tenant) { $Tenant } else { $null }
|    $st.SubscriptionId = if ($Subscription) { $Subscription } else { $null }
|    $st.Cache = @{}
|    return (Get-SIAzContextRest)
|}
|
|function Disconnect-SIAzAccountRest {
|    [CmdletBinding()] param([string]$Scope)
|    $st = Get-SIAzRestState
|    $st.Connection = $null; $st.SubscriptionId = $null; $st.TenantId = $null; $st.Cache = @{}
|    $rc = Get-Variable -Scope Global -Name SI_LogIngestRunCache -ValueOnly -ErrorAction Ignore
|    if ($rc -is [hashtable]) { $rc.Tokens = @{} }
|}
|
|function Disable-SIAzContextAutosaveRest { [CmdletBinding()] param([string]$Scope) }
|
|function Get-SIAzContextRest {
|    <# The context object the call sites read (Subscription.Id / .Name, Tenant.Id, Account.Id / .Type), or $null when
|       no identity is configured. #>
|    [CmdletBinding()] param()
|    try { $a = Resolve-SIAzRestAuth } catch { return $null }
|    $sub = Get-SIAzRestSubscriptionId
|    $tid = Get-SIAzRestTenantId
|    $acct = switch ($a.Mode) { 'ManagedIdentity' { [pscustomobject]@{ Id = $(if ($a.ClientId) { $a.ClientId } else { 'MSI' }); Type = 'ManagedService' } } default { [pscustomobject]@{ Id = $a.AppId; Type = 'ServicePrincipal' } } }
|    return [pscustomobject]@{
|        PSTypeName   = 'SI.AzRest.Context'
|        Name         = ('{0} ({1})' -f $sub, $acct.Id)
|        Account      = $acct
|        Subscription = $(if ($sub) { [pscustomobject]@{ Id = $sub; SubscriptionId = $sub; Name = $sub; TenantId = $tid; ExtendedProperties = @{} } } else { $null })
|        Tenant       = [pscustomobject]@{ Id = $tid; TenantId = $tid }
|        Environment  = [pscustomobject]@{ Name = 'AzureCloud' }
|    }
|}
|
|function Set-SIAzContextRest {
|    [CmdletBinding()]
|    param([Alias('SubscriptionId', 'SubscriptionName')][string]$Subscription, [Alias('TenantId', 'Domain')][string]$Tenant, [object]$Context, [string]$Scope)
|    $st = Get-SIAzRestState
|    if ($Context -and $Context.Subscription) { $Subscription = [string]$Context.Subscription.Id }
|    if ($Subscription) { $st.SubscriptionId = $Subscription }
|    if ($Tenant) { $st.TenantId = $Tenant }
|    return (Get-SIAzContextRest)
|}
|
|function Get-SIAzAccessTokenRest {
|    [CmdletBinding()] param([string]$ResourceUrl, [string]$TenantId)
|    $res = if ($ResourceUrl) { $ResourceUrl } else { 'https://management.azure.com/' }
|    $tok = Get-SIAzureToken -Resource $res
|    $c = ConvertFrom-SIJwtPayload $tok
|    $exp = [DateTimeOffset]::UtcNow.AddMinutes(45)
|    if ($c -and $c.exp) { try { $exp = [DateTimeOffset]::FromUnixTimeSeconds([long]$c.exp) } catch { } }
|    return [pscustomobject]@{ Token = $tok; ExpiresOn = $exp; Type = 'Bearer'; TenantId = $(if ($c) { [string]$c.tid } else { $null }); UserId = $(if ($c) { [string]$c.appid } else { $null }) }
|}
|
|function Get-SIAzSubscriptionRest {
|    [CmdletBinding()] param([string]$TenantId, [string]$SubscriptionId)
|    foreach ($s in @(Invoke-SIArm -Path '/subscriptions' -ApiVersion '2022-12-01' -List)) {
|        if ($TenantId -and [string]$s.tenantId -and [string]$s.tenantId -ne $TenantId) { continue }
|        if ($SubscriptionId -and [string]$s.subscriptionId -ne $SubscriptionId) { continue }
|        [pscustomobject]@{ Id = [string]$s.subscriptionId; SubscriptionId = [string]$s.subscriptionId; Name = [string]$s.displayName; State = [string]$s.state; TenantId = [string]$s.tenantId; HomeTenantId = [string]$s.tenantId }
|    }
|}
|
|function Invoke-SIAzRestMethodRest {
|    <# As Invoke-AzRestMethod: never throws on an HTTP status; returns StatusCode / Content / Headers / Method. #>
|    [CmdletBinding()] param([string]$Path, [string]$Method = 'GET', [string]$Payload)
|    if (-not $Method) { $Method = 'GET' }
|    $uri = if ($Path -match '^https://') { $Path } else { 'https://management.azure.com' + $Path }
|    $body = if ($Payload) { $Payload } else { $null }
|    # #564: a POST action with no body sends '{}' (an empty JSON body was refused with HTTP 415)
|    if ($Method.ToUpperInvariant() -eq 'POST' -and $null -eq $body) { $body = '{}' }
|    # #548: inside an Invardia support session through the recording wrapper, never a raw token
|    if (Test-SISupportRequestRoute -Audience Arm) { $r = Invoke-SISupportHttp -Method $Method -Uri $uri -Body $body -ContentType 'application/json' -Audience Arm }
|    else {
|        $tok = Get-SIAzureToken -Audience Arm
|        $r = Invoke-SIAzRestHttp -Method $Method -Uri $uri -Headers @{ Authorization = ('Bearer ' + $tok) } -Body $body -ContentType 'application/json'
|    }
|    return [pscustomobject]@{ StatusCode = [int]$r.StatusCode; Content = [string]$r.Content; Headers = $r.Headers; Method = $Method.ToUpperInvariant() }
|}
|
|function Invoke-SIAzOperationalInsightsQueryRest {
|    [CmdletBinding()] param([string]$WorkspaceId, [string]$Query, [int]$Wait, [timespan]$Timespan, [switch]$AllowPartial, [scriptblock]$OnPage, [long]$PageBytes)
|    $p = @{ WorkspaceId = $WorkspaceId; Query = $Query }
|    if ($PSBoundParameters.ContainsKey('Wait')) { $p['Wait'] = $Wait }
|    if ($PSBoundParameters.ContainsKey('Timespan')) { $p['Timespan'] = $Timespan }
|    if ($AllowPartial) { $p['AllowPartial'] = $true }
|    if ($OnPage) { $p['OnPage'] = $OnPage }
|    if ($PSBoundParameters.ContainsKey('PageBytes') -and $PageBytes -gt 0) { $p['PageBytes'] = $PageBytes }
|    return (Invoke-SILaQuery @p)
|}
|
|function ConvertTo-SIAzWorkspaceObject {
|    param($Ws)
|    $cid = [guid]::Empty
|    [void][guid]::TryParse([string]$Ws.properties.customerId, [ref]$cid)
|    $rg = if ([string]$Ws.id -match '/resourceGroups/([^/]+)/') { $Matches[1] } else { $null }
|    [pscustomobject]@{
|        Name = [string]$Ws.name; ResourceId = [string]$Ws.id; ResourceGroupName = $rg; Location = [string]$Ws.location
|        CustomerId = $cid; Sku = [string]$Ws.properties.sku.name; RetentionInDays = $Ws.properties.retentionInDays
|        ProvisioningState = [string]$Ws.properties.provisioningState; Tags = $Ws.tags
|    }
|}
|
|function Get-SIAzOperationalInsightsWorkspaceRest {
|    [CmdletBinding()] param([string]$ResourceGroupName, [string]$Name)
|    $sub = Get-SIAzRestSubscriptionId
|    if ($ResourceGroupName -and $Name) {
|        $ws = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.OperationalInsights/workspaces/$Name") -ApiVersion '2022-10-01' -AllowNotFound
|        if (-not $ws) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The Log Analytics workspace '{0}' was not found in resource group '{1}'." -f $Name, $ResourceGroupName) -Target $Name; return }
|        return (ConvertTo-SIAzWorkspaceObject $ws)
|    }
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.OperationalInsights/workspaces" } else { "/subscriptions/$sub/providers/Microsoft.OperationalInsights/workspaces" }
|    foreach ($w in @(Invoke-SIArm -Path $path -ApiVersion '2022-10-01' -List)) {
|        if ($Name -and [string]$w.name -ne $Name) { continue }
|        ConvertTo-SIAzWorkspaceObject $w
|    }
|}
|
|function New-SIAzOperationalInsightsWorkspaceRest {
|    [CmdletBinding()] param([string]$ResourceGroupName, [string]$Name, [string]$Location, [string]$Sku = 'PerGB2018', [int]$RetentionInDays = 30)
|    if (-not $Sku) { $Sku = 'PerGB2018' }
|    $sub = Get-SIAzRestSubscriptionId
|    $body = @{ location = $Location; properties = @{ sku = @{ name = $Sku } } }
|    if ($PSBoundParameters.ContainsKey('RetentionInDays')) { $body.properties['retentionInDays'] = $RetentionInDays }
|    $wsPath = "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.OperationalInsights/workspaces/$Name"
|    $ws = Invoke-SIArm -Method PUT -Path $wsPath -ApiVersion '2022-10-01' -Body $body
|    # the create is asynchronous (its answer can be empty, or a workspace still being made): wait until the workspace is
|    # THERE and provisioned -- its id and customer id are used right after this returns. Not ready in time = a clear stop.
|    $sleep = Get-Variable -Scope Global -Name SI_ArmBusySleep -ValueOnly -ErrorAction Ignore
|    $state = ''
|    for ($i = 0; $i -lt 60; $i++) {
|        $state = if ($ws -and $ws.properties) { [string]$ws.properties.provisioningState } else { '' }
|        if ($ws -and [string]$ws.id -and ($state -eq 'Succeeded' -or -not $state)) { return (ConvertTo-SIAzWorkspaceObject $ws) }
|        if ($state -in 'Failed', 'Canceled') { throw ("The Log Analytics workspace '{0}' was not created: Azure reports it {1} -- see the activity log of resource group '{2}' for its reason." -f $Name, $state, $ResourceGroupName) }
|        if ($sleep -is [scriptblock]) { & $sleep 5 } else { Start-Sleep -Seconds 5 }
|        $ws = Invoke-SIArm -Path $wsPath -ApiVersion '2022-10-01' -AllowNotFound
|    }
|    throw ("The Log Analytics workspace '{0}' is not ready 5 minutes after it was created (Azure shows: {1})." -f $Name, $(if ($state) { $state } else { 'not there yet' }))
|}
|
|function New-SIAzGraphPage {
|    <# A page shaped like Search-AzGraph's response: enumerates as the rows, with .Data and .SkipToken. #>
|    param([object[]]$Rows, [string]$SkipToken)
|    $list = [System.Collections.Generic.List[object]]::new()
|    foreach ($r in @($Rows)) { if ($null -ne $r) { [void]$list.Add($r) } }
|    Add-Member -InputObject $list -NotePropertyName Data -NotePropertyValue $list.ToArray() -Force
|    Add-Member -InputObject $list -NotePropertyName SkipToken -NotePropertyValue $(if ($SkipToken) { $SkipToken } else { $null }) -Force
|    return ,$list
|}
|
|function Search-SIAzGraphRest {
|    [CmdletBinding()] param([string]$Query, [int]$First = 100, [int]$Skip, [string[]]$Subscription, [string[]]$ManagementGroup, [string]$SkipToken)
|    if (-not $PSBoundParameters.ContainsKey('First') -or $First -le 0) { $First = 100 }
|    $page = Invoke-SIResourceGraphPage -Query $Query -Subscription $Subscription -ManagementGroup $ManagementGroup -First $First -Skip $Skip -SkipToken $SkipToken
|    $p = New-SIAzGraphPage -Rows $page.Data -SkipToken $page.SkipToken
|    return ,$p
|}
|
|function Get-SIAzKeyVaultSecretRest {
|    [CmdletBinding()] param([string]$VaultName, [string]$Name, [switch]$AsPlainText)
|    $j = Get-SIKeyVaultSecretRaw -VaultName $VaultName -Name $Name
|    if (-not $j) { return }
|    if ($AsPlainText) { return [string]$j.value }
|    $sec = New-Object System.Security.SecureString
|    foreach ($ch in ([string]$j.value).ToCharArray()) { $sec.AppendChar($ch) }
|    $sec.MakeReadOnly()
|    return [pscustomobject]@{ VaultName = $VaultName; Name = $Name; Id = [string]$j.id; SecretValue = $sec; ContentType = [string]$j.contentType; Enabled = $j.attributes.enabled; Tags = $j.tags }
|}
|
|function Set-SIAzKeyVaultSecretRest {
|    <# PUT secrets/{name}: a new version of the secret. -SecretValue is a SecureString (as for the cmdlet) or plain text. #>
|    [CmdletBinding()] param([string]$VaultName, [string]$Name, $SecretValue, [string]$ContentType)
|    $plain = if ($SecretValue -is [System.Security.SecureString]) { [System.Net.NetworkCredential]::new('', $SecretValue).Password } else { [string]$SecretValue }
|    $body = @{ value = $plain }
|    if ($ContentType) { $body.contentType = $ContentType }
|    $uri = 'https://{0}.vault.azure.net/secrets/{1}?api-version=7.4' -f $VaultName, [uri]::EscapeDataString($Name)
|    $r = Invoke-SIAzRestRequest -Method PUT -Uri $uri -Audience KeyVault -Body ($body | ConvertTo-Json -Compress) -What ("Key Vault secret '{0}' in '{1}'" -f $Name, $VaultName)
|    $j = $r.Content | ConvertFrom-Json
|    return [pscustomobject]@{ VaultName = $VaultName; Name = $Name; Id = [string]$j.id; ContentType = [string]$j.contentType; Enabled = $j.attributes.enabled }
|}
|
|function ConvertTo-SIAzResourceGroupObject {
|    param($Rg)
|    [pscustomobject]@{ ResourceGroupName = [string]$Rg.name; Location = [string]$Rg.location; ResourceId = [string]$Rg.id; ProvisioningState = [string]$Rg.properties.provisioningState; Tags = $Rg.tags }
|}
|
|function Get-SIAzResourceGroupRest {
|    [CmdletBinding()] param([string]$Name)
|    $sub = Get-SIAzRestSubscriptionId
|    if ($Name) {
|        $rg = Invoke-SIArm -Path ("/subscriptions/$sub/resourcegroups/$Name") -ApiVersion '2021-04-01' -AllowNotFound
|        if (-not $rg) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("Provided resource group '{0}' does not exist." -f $Name) -Target $Name; return }
|        return (ConvertTo-SIAzResourceGroupObject $rg)
|    }
|    foreach ($rg in @(Invoke-SIArm -Path ("/subscriptions/$sub/resourcegroups") -ApiVersion '2021-04-01' -List)) { ConvertTo-SIAzResourceGroupObject $rg }
|}
|
|function New-SIAzResourceGroupRest {
|    [CmdletBinding()] param([string]$Name, [string]$Location, [hashtable]$Tag)
|    $sub = Get-SIAzRestSubscriptionId
|    $body = @{ location = $Location }
|    if ($Tag) { $body['tags'] = $Tag }
|    $rg = Invoke-SIArm -Method PUT -Path ("/subscriptions/$sub/resourcegroups/$Name") -ApiVersion '2021-04-01' -Body $body
|    return (ConvertTo-SIAzResourceGroupObject $rg)
|}
|
|function Get-SIAzRestRoleDefinitions {
|    <# Role definitions visible at -Scope (built-in + custom), cached per scope for the run. #>
|    param([string]$Scope, [switch]$CustomOnly)
|    $st = Get-SIAzRestState
|    $key = 'roledefs|' + $Scope.ToLowerInvariant() + '|' + [string][bool]$CustomOnly
|    if ($st.Cache.ContainsKey($key)) { return $st.Cache[$key] }
|    $path = $Scope.TrimEnd('/') + '/providers/Microsoft.Authorization/roleDefinitions'
|    if ($CustomOnly) { $path += '?$filter=' + [uri]::EscapeDataString("type eq 'CustomRole'") }
|    $defs = @(Invoke-SIArm -Path $path -ApiVersion '2022-04-01' -List)
|    $st.Cache[$key] = $defs
|    return $defs
|}
|
|function Get-SIAzRestRoleDefinitionNames {
|    <#
|        The role NAME of every role definition visible at -Scope, by its id (lowercase): @{ <id> = <roleName> }. For the
|        role-assignment read, which needs only the name. Built-in roles are the same at every scope: they are read ONCE per
|        run and kept as names only; a scope's custom roles are read per scope, names only. The full definitions (every
|        permission of ~800 built-in roles) are never kept. customer B 2026-10-15: the identity producer read the role
|        assignments of 1,195 subscriptions and kept the WHOLE definition list of every one of them (Get-SIAzRestRoleDefinitions
|        caches per scope) -- the process ran out of memory in its sixth minute and every read after that failed.
|        -Fetch (tests): { param($Path) } -> the ARM rows of that list.
|    #>
|    param([Parameter(Mandatory)][string]$Scope, [scriptblock]$Fetch)
|    $st = Get-SIAzRestState
|    $read = { param($p) if ($Fetch) { @(& $Fetch $p) } else { @(Invoke-SIArm -Path $p -ApiVersion '2022-04-01' -List) } }
|    $base = $Scope.TrimEnd('/') + '/providers/Microsoft.Authorization/roleDefinitions?$filter='
|    $bk = 'roledefnames|builtin'
|    if (-not $st.Cache.ContainsKey($bk)) {
|        $m = @{}
|        foreach ($d in (& $read ($base + [uri]::EscapeDataString("type eq 'BuiltInRole'")))) { if ($d -and $d.name) { $m[([string]$d.name).ToLowerInvariant()] = [string]$d.properties.roleName } }
|        $st.Cache[$bk] = $m
|    }
|    $ck = 'roledefnames|custom|' + $Scope.ToLowerInvariant()
|    if (-not $st.Cache.ContainsKey($ck)) {
|        $m = @{}
|        foreach ($d in (& $read ($base + [uri]::EscapeDataString("type eq 'CustomRole'")))) { if ($d -and $d.name) { $m[([string]$d.name).ToLowerInvariant()] = [string]$d.properties.roleName } }
|        $st.Cache[$ck] = $m
|    }
|    [pscustomobject]@{ BuiltIn = $st.Cache[$bk]; Custom = $st.Cache[$ck] }
|}
|
|function ConvertTo-SIAzRoleDefinitionObject {
|    param($D)
|    $perm = @($D.properties.permissions) | Select-Object -First 1
|    [pscustomobject]@{
|        Name = [string]$D.properties.roleName; Id = [string]$D.name; IsCustom = ([string]$D.properties.type -eq 'CustomRole')
|        Description = [string]$D.properties.description
|        Actions = @($perm.actions); NotActions = @($perm.notActions); DataActions = @($perm.dataActions); NotDataActions = @($perm.notDataActions)
|        AssignableScopes = @($D.properties.assignableScopes)
|    }
|}
|
|function Get-SIAzRoleDefinitionRest {
|    [CmdletBinding()] param([switch]$Custom, [string]$Name, [string]$Scope)
|    if (-not $Scope) { $Scope = '/subscriptions/' + (Get-SIAzRestSubscriptionId) }
|    $out = @(Get-SIAzRestRoleDefinitions -Scope $Scope -CustomOnly:$Custom | ForEach-Object { ConvertTo-SIAzRoleDefinitionObject $_ })
|    if ($Name) { $out = @($out | Where-Object { $_.Name -eq $Name }) }
|    return $out
|}
|
|function Resolve-SIAzRestPrincipalNames {
|    <# DisplayName per object id, best effort (Microsoft Graph directoryObjects/getByIds). Empty on any failure: a name
|       is informational, never a reason to fail the read. #>
|    param([string[]]$Ids)
|    $map = @{}
|    $ids = @($Ids | Where-Object { $_ } | Select-Object -Unique)
|    for ($i = 0; $i -lt $ids.Count; $i += 1000) {
|        $chunk = @($ids[$i..([Math]::Min($i + 999, $ids.Count - 1))])
|        try {
|            $r = Invoke-SIAzRestRequest -Method POST -Uri 'https://graph.microsoft.com/v1.0/directoryObjects/getByIds' -Audience Graph `
|                     -Body (@{ ids = $chunk } | ConvertTo-Json -Compress) -What 'Microsoft Graph getByIds' -MaxAttempts 3
|            foreach ($o in @(($r.Content | ConvertFrom-Json).value)) { if ($o.id) { $map[[string]$o.id] = [string]$o.displayName } }
|        } catch { Write-Verbose ('principal names not resolved: {0}' -f $_.Exception.Message) }
|    }
|    return $map
|}
|
|function Get-SIAzRoleAssignmentRest {
|    [CmdletBinding()] param([string]$ObjectId, [string]$Scope, [string]$RoleDefinitionName)
|    $explicitScope = [bool]$Scope
|    if (-not $Scope) { $Scope = '/subscriptions/' + (Get-SIAzRestSubscriptionId) }
|    $path = $Scope.TrimEnd('/') + '/providers/Microsoft.Authorization/roleAssignments'
|    if ($ObjectId) { $path += '?$filter=' + [uri]::EscapeDataString(("principalId eq '{0}'" -f $ObjectId)) }
|    elseif ($explicitScope) { $path += '?$filter=' + [uri]::EscapeDataString('atScope()') }
|    $items = @(Invoke-SIArm -Path $path -ApiVersion '2022-04-01' -List)
|    $subScope = if ($Scope -match '^(/subscriptions/[^/]+)') { $Matches[1] } else { $Scope }
|    # names only, built-ins read once per run (Get-SIAzRestRoleDefinitionNames) -- never the whole definition list per scope
|    $defs = Get-SIAzRestRoleDefinitionNames -Scope $subScope
|    $names = Resolve-SIAzRestPrincipalNames -Ids @($items | ForEach-Object { [string]$_.properties.principalId })
|    foreach ($a in $items) {
|        $rdId = ([string]$a.properties.roleDefinitionId -split '/')[-1]
|        $rdKey = $rdId.ToLowerInvariant()
|        $rdName = if ($defs.BuiltIn.ContainsKey($rdKey)) { $defs.BuiltIn[$rdKey] } else { $defs.Custom[$rdKey] }
|        if ($RoleDefinitionName -and $rdName -ne $RoleDefinitionName) { continue }
|        $oid = [string]$a.properties.principalId
|        [pscustomobject]@{
|            RoleAssignmentId = [string]$a.id; RoleAssignmentName = [string]$a.name; Scope = [string]$a.properties.scope
|            DisplayName = $(if ($names.ContainsKey($oid)) { $names[$oid] } else { $null }); SignInName = $null
|            RoleDefinitionName = $rdName; RoleDefinitionId = $rdId; ObjectId = $oid; ObjectType = [string]$a.properties.principalType
|            CanDelegate = $false; Condition = $a.properties.condition; Description = [string]$a.properties.description
|        }
|    }
|}
|
|function New-SIAzRoleAssignmentRest {
|    # -Description (optional): stored on the assignment itself -- who gave it and why survives on Azure's side, so a later
|    # run can find an assignment it gave even when its own record of that is gone
|    [CmdletBinding()] param([string]$ObjectId, [string]$Scope, [string]$RoleDefinitionName, [string]$Description)
|    $subScope = if ($Scope -match '^(/subscriptions/[^/]+)') { $Matches[1] } else { $Scope }
|    $def = @(Get-SIAzRestRoleDefinitions -Scope $subScope | Where-Object { [string]$_.properties.roleName -eq $RoleDefinitionName }) | Select-Object -First 1
|    if (-not $def) { throw ("The role definition '{0}' was not found at scope '{1}'." -f $RoleDefinitionName, $subScope) }
|    $name = [guid]::NewGuid().ToString()
|    $body = @{ properties = @{ roleDefinitionId = [string]$def.id; principalId = $ObjectId } }
|    if ("$Description".Trim()) { $body.properties['description'] = "$Description".Trim() }
|    $a = Invoke-SIArm -Method PUT -Path ($Scope.TrimEnd('/') + '/providers/Microsoft.Authorization/roleAssignments/' + $name) -ApiVersion '2022-04-01' -Body $body
|    return [pscustomobject]@{ RoleAssignmentId = [string]$a.id; RoleAssignmentName = [string]$a.name; Scope = $Scope; RoleDefinitionName = $RoleDefinitionName; RoleDefinitionId = [string]$def.name; ObjectId = $ObjectId; ObjectType = [string]$a.properties.principalType }
|}
|
|function Get-SIAzTagRest {
|    [CmdletBinding()] param([string]$ResourceId)
|    $t = Invoke-SIArm -Path ($ResourceId.TrimEnd('/') + '/providers/Microsoft.Resources/tags/default') -ApiVersion '2021-04-01'
|    $h = @{}
|    if ($t -and $t.properties -and $t.properties.tags) { foreach ($p in $t.properties.tags.PSObject.Properties) { $h[$p.Name] = [string]$p.Value } }
|    return [pscustomobject]@{ Id = [string]$t.id; Name = 'default'; Properties = [pscustomobject]@{ TagsProperty = $h } }
|}
|
|function Update-SIAzTagRest {
|    [CmdletBinding()] param([string]$ResourceId, [hashtable]$Tag, [string]$Operation = 'Merge')
|    if (-not $Operation) { $Operation = 'Merge' }
|    $t = Invoke-SIArm -Method PATCH -Path ($ResourceId.TrimEnd('/') + '/providers/Microsoft.Resources/tags/default') -ApiVersion '2021-04-01' -Body @{ operation = $Operation; properties = @{ tags = $Tag } }
|    $h = @{}
|    if ($t -and $t.properties -and $t.properties.tags) { foreach ($p in $t.properties.tags.PSObject.Properties) { $h[$p.Name] = [string]$p.Value } }
|    return [pscustomobject]@{ Id = [string]$t.id; Name = 'default'; Properties = [pscustomobject]@{ TagsProperty = $h } }
|}
|
|function Get-SIAzADServicePrincipalRest {
|    [CmdletBinding()] param([string]$ApplicationId, [string]$ObjectId)
|    $uri = if ($ObjectId) { 'https://graph.microsoft.com/v1.0/servicePrincipals/{0}?$select=id,appId,displayName,servicePrincipalNames' -f $ObjectId }
|           else { 'https://graph.microsoft.com/v1.0/servicePrincipals?$filter={0}&$select=id,appId,displayName,servicePrincipalNames' -f [uri]::EscapeDataString(("appId eq '{0}'" -f $ApplicationId)) }
|    $r = Invoke-SIAzRestRequest -Method GET -Uri $uri -Audience Graph -AllowNotFound -What 'Microsoft Graph service principal'
|    if (-not $r) { return }
|    $j = $r.Content | ConvertFrom-Json
|    $items = if ($j.PSObject.Properties['value']) { @($j.value) } else { @($j) }
|    foreach ($s in $items) { if ($s) { [pscustomobject]@{ Id = [string]$s.id; AppId = [string]$s.appId; DisplayName = [string]$s.displayName; ServicePrincipalName = @($s.servicePrincipalNames) } } }
|}
|
|function ConvertTo-SIAzDceObject {
|    param($D)
|    [pscustomobject]@{
|        Name = [string]$D.name; Id = [string]$D.id; Location = [string]$D.location
|        LogIngestionEndpoint = [string]$D.properties.logsIngestion.endpoint; ConfigurationAccessEndpoint = [string]$D.properties.configurationAccess.endpoint
|        NetworkAclsPublicNetworkAccess = [string]$D.properties.networkAcls.publicNetworkAccess; ProvisioningState = [string]$D.properties.provisioningState
|    }
|}
|
|function Get-SIAzDataCollectionEndpointRest {
|    [CmdletBinding()] param([string]$Name, [string]$ResourceGroupName)
|    $sub = Get-SIAzRestSubscriptionId
|    if ($Name -and $ResourceGroupName) {
|        $d = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Insights/dataCollectionEndpoints/$Name") -ApiVersion '2022-06-01' -AllowNotFound
|        if (-not $d) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The data collection endpoint '{0}' was not found in resource group '{1}'." -f $Name, $ResourceGroupName) -Target $Name; return }
|        return (ConvertTo-SIAzDceObject $d)
|    }
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Insights/dataCollectionEndpoints" } else { "/subscriptions/$sub/providers/Microsoft.Insights/dataCollectionEndpoints" }
|    foreach ($d in @(Invoke-SIArm -Path $path -ApiVersion '2022-06-01' -List)) { if (-not $Name -or [string]$d.name -eq $Name) { ConvertTo-SIAzDceObject $d } }
|}
|
|function New-SIAzDataCollectionEndpointRest {
|    [CmdletBinding()] param([string]$Name, [string]$ResourceGroupName, [string]$Location, [string]$NetworkAclsPublicNetworkAccess = 'Enabled')
|    if (-not $NetworkAclsPublicNetworkAccess) { $NetworkAclsPublicNetworkAccess = 'Enabled' }
|    $sub = Get-SIAzRestSubscriptionId
|    $d = Invoke-SIArm -Method PUT -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Insights/dataCollectionEndpoints/$Name") -ApiVersion '2022-06-01' `
|             -Body @{ location = $Location; properties = @{ networkAcls = @{ publicNetworkAccess = $NetworkAclsPublicNetworkAccess } } }
|    return (ConvertTo-SIAzDceObject $d)
|}
|
|function Get-SIAzDataCollectionRuleRest {
|    [CmdletBinding()] param([string]$Name, [string]$ResourceGroupName)
|    $sub = Get-SIAzRestSubscriptionId
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Insights/dataCollectionRules" } else { "/subscriptions/$sub/providers/Microsoft.Insights/dataCollectionRules" }
|    foreach ($d in @(Invoke-SIArm -Path $path -ApiVersion '2022-06-01' -List)) {
|        if ($Name -and [string]$d.name -ne $Name) { continue }
|        [pscustomobject]@{ Name = [string]$d.name; Id = [string]$d.id; Location = [string]$d.location; ImmutableId = [string]$d.properties.immutableId; DataCollectionEndpointId = [string]$d.properties.dataCollectionEndpointId }
|    }
|}
|
|function New-SIAzStorageContextRest {
|    <# The storage "context" the REST path needs: the account name (and its endpoints). Every call
|       signs in with the run's identity (OAuth); there is no account-key form. #>
|    [CmdletBinding()] param([string]$StorageAccountName, [switch]$UseConnectedAccount)
|    return [pscustomobject]@{
|        PSTypeName = 'SI.AzRest.StorageContext'; SIRest = $true; StorageAccountName = $StorageAccountName
|        BlobEndPoint = ('https://{0}.blob.core.windows.net/' -f $StorageAccountName)
|        QueueEndPoint = ('https://{0}.queue.core.windows.net/' -f $StorageAccountName)
|        TableEndPoint = ('https://{0}.table.core.windows.net/' -f $StorageAccountName)
|    }
|}
|
|function Get-SIAzRestStorageAccountName {
|    param($Context)
|    if ($null -eq $Context) { throw 'No storage context was given.' }
|    $n = [string]$Context.StorageAccountName
|    if (-not $n) { throw 'The storage context does not name a storage account.' }
|    return $n
|}
|
|function ConvertTo-SIAzStorageAccountObject {
|    param($S)
|    $rg = if ([string]$S.id -match '/resourceGroups/([^/]+)/') { $Matches[1] } else { $null }
|    [pscustomobject]@{
|        StorageAccountName = [string]$S.name; ResourceGroupName = $rg; Id = [string]$S.id; Location = [string]$S.location
|        Kind = [string]$S.kind; Sku = $S.sku; PrimaryEndpoints = $S.properties.primaryEndpoints; ProvisioningState = [string]$S.properties.provisioningState
|        Context = (New-SIAzStorageContextRest -StorageAccountName ([string]$S.name) -UseConnectedAccount)
|    }
|}
|
|function Get-SIAzStorageAccountRest {
|    [CmdletBinding()] param([string]$ResourceGroupName, [string]$Name)
|    $sub = Get-SIAzRestSubscriptionId
|    if ($ResourceGroupName -and $Name) {
|        $s = Invoke-SIArm -Path ("/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Storage/storageAccounts/$Name") -ApiVersion '2023-01-01' -AllowNotFound
|        if (-not $s) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("The storage account '{0}' was not found in resource group '{1}'." -f $Name, $ResourceGroupName) -Target $Name; return }
|        return (ConvertTo-SIAzStorageAccountObject $s)
|    }
|    $path = if ($ResourceGroupName) { "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Storage/storageAccounts" } else { "/subscriptions/$sub/providers/Microsoft.Storage/storageAccounts" }
|    foreach ($s in @(Invoke-SIArm -Path $path -ApiVersion '2023-01-01' -List)) { if (-not $Name -or [string]$s.name -eq $Name) { ConvertTo-SIAzStorageAccountObject $s } }
|}
|
|function Get-SIStorageAccountCreateProperties {
|    <#
|        PURE. The properties EVERY storage account SecurityInsight creates gets: shared-key access OFF (no account key
|        and no key-signed SAS works -- a user-delegation SAS still does), Entra ID the default in the portal, HTTPS only,
|        TLS 1.2 at least, no public blob access. Every SecurityInsight host reaches its storage with its own identity
|        (Storage Blob / Queue / Table Data roles), so nothing needs a key. An EXISTING account is never changed here;
|        setup\Set-SIStorageSharedKey.ps1 -Disable switches one off after checking nothing still uses a key.
|    #>
|    return @{
|        supportsHttpsTrafficOnly     = $true
|        allowBlobPublicAccess        = $false
|        allowSharedKeyAccess         = $false
|        defaultToOAuthAuthentication = $true
|        minimumTlsVersion            = 'TLS1_2'
|    }
|}
|
|function New-SIAzStorageAccountRest {
|    [CmdletBinding()]
|    param([string]$ResourceGroupName, [string]$Name, [string]$Location, [string]$SkuName, [string]$Kind, [bool]$EnableHttpsTrafficOnly = $true,
|          [string]$MinimumTlsVersion, [bool]$AllowBlobPublicAccess = $false,
|          # #866 (a private install): 'Disabled' CREATES the account with no public access -- only its private endpoints
|          [ValidateSet('', 'Disabled')][string]$PublicNetworkAccess = '')
|    $sub = Get-SIAzRestSubscriptionId
|    # -EnableHttpsTrafficOnly / -MinimumTlsVersion / -AllowBlobPublicAccess keep the Az cmdlet's shape, but a NEW
|    # account is always created locked down (Get-SIStorageAccountCreateProperties): no caller can weaken it.
|    $props = Get-SIStorageAccountCreateProperties
|    if ($PublicNetworkAccess -eq 'Disabled') { $props['publicNetworkAccess'] = 'Disabled' }
|    $path = "/subscriptions/$sub/resourceGroups/$ResourceGroupName/providers/Microsoft.Storage/storageAccounts/$Name"
|    $null = Invoke-SIArm -Method PUT -Path $path -ApiVersion '2023-01-01' -Body @{ location = $Location; sku = @{ name = $SkuName }; kind = $Kind; properties = $props }
|    # the create is asynchronous: wait until the account is THERE AND PROVISIONED (10 minutes at most) -- what follows
|    # (its roles, its containers) is refused "operation in progress" on an account Azure is still making. A "not found"
|    # in between is "not yet"; an account that is not ready in time is a clear stop, never handed on as if it were.
|    $s = $null; $state = ''
|    $sleep = Get-Variable -Scope Global -Name SI_ArmBusySleep -ValueOnly -ErrorAction Ignore
|    for ($i = 0; $i -lt 120; $i++) {
|        $s = Invoke-SIArm -Path $path -ApiVersion '2023-01-01' -AllowNotFound
|        $state = if ($s -and $s.properties) { [string]$s.properties.provisioningState } else { '' }
|        if ($s -and ($state -eq 'Succeeded' -or -not $state)) { return (ConvertTo-SIAzStorageAccountObject $s) }
|        if ($state -in 'Failed', 'Canceled') { throw ("The storage account '{0}' was not created: Azure reports it {1} -- see the activity log of resource group '{2}' for its reason." -f $Name, $state, $ResourceGroupName) }
|        if ($sleep -is [scriptblock]) { & $sleep 5 } else { Start-Sleep -Seconds 5 }
|    }
|    if (-not $s) { throw ("The storage account '{0}' was requested but did not appear." -f $Name) }
|    throw ("The storage account '{0}' is not ready 10 minutes after it was created (Azure shows: {1})." -f $Name, $(if ($state) { $state } else { 'no state' }))
|}
|
|function Get-SIAzStorageContainerRest {
|    [CmdletBinding()] param([string]$Name, [object]$Context)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    $c = Test-SIBlobContainer -Account $acct -Container $Name
|    if (-not $c) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("Can not find the container '{0}' (ContainerNotFound)." -f $Name) -Target $Name; return }
|    return $c
|}
|
|function New-SIAzStorageContainerRest {
|    [CmdletBinding()] param([string]$Name, [object]$Context, [string]$Permission)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    return (New-SIBlobContainer -Account $acct -Container $Name)
|}
|
|function ConvertTo-SIAzBlobObject {
|    <# A blob shaped like Get-AzStorageBlob's: Name / Length / LastModified / ETag, and the ICloudBlob members the call
|       sites read (Name, Container.Name, Properties.ETag / LastModified / Length). #>
|    param($B, [string]$Account)
|    $cloud = [pscustomobject]@{
|        Name = $B.Name; SIAccount = $Account
|        Container = [pscustomobject]@{ Name = $B.Container }
|        Properties = [pscustomobject]@{ ETag = $B.ETag; LastModified = $B.LastModified; Length = $B.Length; ContentType = $B.ContentType }
|    }
|    [pscustomobject]@{ Name = $B.Name; Length = $B.Length; LastModified = $B.LastModified; ETag = $B.ETag; ContentType = $B.ContentType; BlobType = 'BlockBlob'; ICloudBlob = $cloud }
|}
|
|function Get-SIAzStorageBlobRest {
|    [CmdletBinding()] param([string]$Container, [string]$Blob, [string]$Prefix, [object]$Context)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    if ($Blob) {
|        $b = Get-SIBlobProperties -Account $acct -Container $Container -Blob $Blob
|        if (-not $b) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("Can not find blob '{0}' in container '{1}' (BlobNotFound)." -f $Blob, $Container) -Target $Blob; return }
|        return (ConvertTo-SIAzBlobObject $b $acct)
|    }
|    foreach ($b in @(Get-SIBlobList -Account $acct -Container $Container -Prefix $Prefix)) { ConvertTo-SIAzBlobObject $b $acct }
|}
|
|function Get-SIAzStorageBlobContentRest {
|    [CmdletBinding()] param([string]$Container, [string]$Blob, [object]$CloudBlob, [string]$Destination, [object]$Context, [switch]$Force)
|    if ($CloudBlob) { $Blob = [string]$CloudBlob.Name; $Container = [string]$CloudBlob.Container.Name }
|    $acct = if ($Context) { Get-SIAzRestStorageAccountName -Context $Context } else { [string]$CloudBlob.SIAccount }
|    $target = $Destination
|    if (-not $target) { $target = (Get-Location).Path }
|    if (Test-Path -LiteralPath $target -PathType Container) { $target = [System.IO.Path]::Combine($target, ($Blob -replace '/', [System.IO.Path]::DirectorySeparatorChar)) }
|    $dir = Split-Path -Parent $target
|    if ($dir -and -not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
|    $null = Get-SIBlobContent -Account $acct -Container $Container -Blob $Blob -Destination $target
|    $b = Get-SIBlobProperties -Account $acct -Container $Container -Blob $Blob
|    if ($b) { return (ConvertTo-SIAzBlobObject $b $acct) }
|}
|
|function Set-SIAzStorageBlobContentRest {
|    [CmdletBinding()] param([string]$File, [string]$Container, [string]$Blob, [object]$Context, [switch]$Force)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    if (-not $Blob) { $Blob = Split-Path -Leaf $File }
|    $etag = Set-SIBlobContent -Account $acct -Container $Container -Blob $Blob -File $File
|    $len = (Get-Item -LiteralPath $File).Length
|    return (ConvertTo-SIAzBlobObject ([pscustomobject]@{ Name = $Blob; Container = $Container; Length = $len; LastModified = [DateTimeOffset]::UtcNow; ETag = $etag; ContentType = 'application/octet-stream' }) $acct)
|}
|
|function Remove-SIAzStorageBlobRest {
|    [CmdletBinding()] param([string]$Container, [string]$Blob, [object]$Context, [switch]$Force)
|    Remove-SIBlob -Account (Get-SIAzRestStorageAccountName -Context $Context) -Container $Container -Blob $Blob
|}
|
|function Start-SIAzStorageBlobCopyRest {
|    <# A copy within the account: download and upload (the files SI copies are small exports), so no SAS and no
|       copy-source authorization is needed. #>
|    [CmdletBinding()] param([string]$SrcContainer, [string]$SrcBlob, [string]$DestContainer, [string]$DestBlob, [object]$Context, [switch]$Force)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    $bytes = Get-SIBlobContent -Account $acct -Container $SrcContainer -Blob $SrcBlob
|    $null = Set-SIBlobContent -Account $acct -Container $DestContainer -Blob $DestBlob -Bytes $bytes
|    return [pscustomobject]@{ Name = $DestBlob; Container = $DestContainer }
|}
|
|function New-SIAzQueueObject {
|    <# A queue shaped like Get-AzStorageQueue's: .QueueClient with SendMessage / ReceiveMessage / DeleteMessage, as the
|       worker queue calls them. #>
|    param([string]$Account, [string]$Name)
|    $client = [pscustomobject]@{ Name = $Name; SIAccount = $Account }
|    $client | Add-Member -MemberType ScriptMethod -Name SendMessage -Value { param($Text) Send-SIQueueMessage -Account $this.SIAccount -Queue $this.Name -Text ([string]$Text) }
|    $client | Add-Member -MemberType ScriptMethod -Name ReceiveMessage -Value {
|        param($VisibilityTimeout)
|        $secs = if ($VisibilityTimeout -is [timespan]) { [int]$VisibilityTimeout.TotalSeconds } elseif ($VisibilityTimeout) { [int]$VisibilityTimeout } else { 30 }
|        [pscustomobject]@{ Value = (Receive-SIQueueMessage -Account $this.SIAccount -Queue $this.Name -VisibilityTimeoutSeconds $secs) }
|    }
|    $client | Add-Member -MemberType ScriptMethod -Name DeleteMessage -Value { param($Id, $PopReceipt) Remove-SIQueueMessage -Account $this.SIAccount -Queue $this.Name -MessageId ([string]$Id) -PopReceipt ([string]$PopReceipt) }
|    return [pscustomobject]@{ Name = $Name; QueueClient = $client }
|}
|
|function Get-SIAzStorageQueueRest {
|    [CmdletBinding()] param([string]$Name, [object]$Context)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    if (-not (Test-SIQueue -Account $acct -Queue $Name)) { Write-SIAzRestNotFound -Cmdlet $PSCmdlet -Message ("Can not find queue '{0}' (QueueNotFound)." -f $Name) -Target $Name; return }
|    return (New-SIAzQueueObject -Account $acct -Name $Name)
|}
|
|function New-SIAzStorageQueueRest {
|    [CmdletBinding()] param([string]$Name, [object]$Context)
|    $acct = Get-SIAzRestStorageAccountName -Context $Context
|    New-SIQueue -Account $acct -Queue $Name
|    return (New-SIAzQueueObject -Account $acct -Name $Name)
|}
|
|# #639 lane 4: a read in parts when one answer cannot carry it (Read-SILaParts) -- for every reader of a large result.
|# Loaded LAST: it reads through this file's Invoke-SIAzOperationalInsightsQuery (and loads this file itself when it is
|# dot-sourced alone, guarded on Invoke-SIArm -- defined by now, so never twice).
|if (-not (Get-Command -Name Read-SILaParts -ErrorAction Ignore)) {
|    $__siLaParts = [System.IO.Path]::Combine($PSScriptRoot, 'SI-LaParts.ps1')
|    if ([System.IO.File]::Exists($__siLaParts)) { . $__siLaParts }
|}
'@ }
$__siSupportFiles['engine/_shared/SI-LaStreamRead.ps1'] = @{ Sha256 = '76262967b7a09e5713b4687cf62f9267864ddcc0f3f11e678958f17226738511'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- A LOG ANALYTICS ANSWER READ AS IT ARRIVES, NEVER HELD WHOLE (Risk Analysis' lookups and answers;
|    owner rule "same method, all sizes; stream always").
|
|    The lean read (#639, SI-AzRest.ps1 ConvertFrom-SILaQueryRows) reads the answer's BYTES into one array of their full
|    length, parses them into a JsonDocument (an index of every token beside them), and only then builds the rows -- so
|    while a lookup is read the process holds the whole answer about three times (bytes + index + rows). A Risk Analysis
|    lookup at a large install is a tenant-sized answer (the identity CI lookup of a 153,000-user tenant: every key of every
|    identity), read in parts of up to the service's own answer limit; the large install's Risk Analysis job ran out of
|    memory on 2 CPU / 4 GiB (#730).
|
|    Here the response stream is read through a small buffer: each ROW is parsed when its bytes are in, turned into the row
|    object at once, and its bytes are let go. Only the rows are held -- the same rows the lean read builds: the same
|    columns in the same order, the same TEXT values (strings as sent, numbers in the service's own spelling, true / false,
|    null stays null, a nested value as its raw JSON text), the table named PrimaryResult else the first, the column list
|    (name / type) and the partial-error object. Compact rows (SI_LaCompactRows, Get-SILaCompactRowType) when the caller
|    asks for them, PSCustomObject rows otherwise.
|
|    pwsh 7 only (System.Text.Json's Utf8JsonReader, compiled once per process with Add-Type). Windows PowerShell, or a
|    process where the reader cannot be compiled: Get-SILaStreamReaderType answers $null and the caller keeps the lean read.
|
|    #836 (found 2026-10-20): NOTHING HERE LIVES ONLY IN THIS FILE'S SCRIPT SCOPE. A function reads $script: of its CALLER's
|    script, and in a container the entry point (container\Start-SIInContainer.ps1) dot-sources SI-AzRest.ps1 -> this file
|    in ITS scope while every engine runs as its own script and skips reloading it -- so a $script: source was $null there,
|    Add-Type failed, the failure was swallowed and no container engine ever streamed. The C# source comes from a FUNCTION
|    (Get-SILaStreamReaderSource), the compiled type is found by its name, and the state a run must share (the reader is off
|    and why, the last read's numbers) is $global:. The older read stays the fallback, but it is never silent: one plain line
|    on the run log says the older read is used and why (Write-SILaStreamFallback).
|#>
|
|function Get-SILaStreamReaderSource {
|    <# The reader's C# source. A FUNCTION, never a $script: variable (#836): callable from any script's scope. #>
|    @'
|using System;
|using System.Collections.Generic;
|using System.IO;
|using System.Management.Automation;
|using System.Reflection;
|using System.Text;
|using System.Text.Json;
|
|namespace SecurityInsight.LaStream
|{
|    public sealed class LaStreamAnswer
|    {
|        public object[] Rows { get; set; }
|        public string[] ColumnNames { get; set; }
|        public string[] ColumnTypes { get; set; }
|        public string ErrorJson { get; set; }
|        public long BytesRead { get; set; }
|        public int LargestBuffer { get; set; }
|        // with a page callback: the rows handed on and in how many pages (Rows is then empty)
|        public long RowsDelivered { get; set; }
|        public int Pages { get; set; }
|    }
|
|    // the caller's own page callback failed -- not a fault of the reader or of the answer
|    public sealed class LaStreamPageException : Exception
|    {
|        public LaStreamPageException(Exception inner) : base("the page callback failed: " + (inner == null ? "" : inner.Message), inner) { }
|    }
|
|    public static class LaStreamReader
|    {
|        // the rows handed on a page at a time: the table being handed on, the answer bytes of the rows waiting, the totals
|        private sealed class PageSink
|        {
|            public Action<object[]> On;
|            public long Limit;
|            public long Bytes;
|            public object Table;
|            public bool FromNonPrimary;
|            public long Rows;
|            public int Pages;
|        }
|
|        private static void Flush(PageSink sink, List<object> rows)
|        {
|            if (sink == null || rows == null || rows.Count == 0) { if (sink != null) sink.Bytes = 0; return; }
|            object[] page = rows.ToArray();
|            rows.Clear();
|            sink.Bytes = 0;
|            try { sink.On(page); }
|            catch (Exception e) { throw new LaStreamPageException(e); }
|            sink.Rows += page.Length;
|            sink.Pages++;
|        }
|
|        public static LaStreamAnswer Read(Stream stream, bool compact, Func<string[], ConstructorInfo> compactCtorFor, int bufferSize, Func<string[], string[], object> plainRowFor)
|        {
|            return Read(stream, compact, compactCtorFor, bufferSize, plainRowFor, null, 0);
|        }
|
|        // onPage: the primary table's rows are handed on a page at a time (about pageBytes of the answer each) and never
|        // collected; the answer's Rows is then empty, RowsDelivered / Pages say what was handed on
|        public static LaStreamAnswer Read(Stream stream, bool compact, Func<string[], ConstructorInfo> compactCtorFor, int bufferSize, Func<string[], string[], object> plainRowFor, Action<object[]> onPage, long pageBytes)
|        {
|            PageSink sink = onPage == null ? null : new PageSink { On = onPage, Limit = Math.Max(1024, pageBytes) };
|            return ReadCore(stream, compact, compactCtorFor, bufferSize, plainRowFor, sink);
|        }
|
|        private enum Ctx { Root, Tables, Table, Columns, Rows, Done }
|
|        private sealed class TableAcc
|        {
|            public int Index;
|            public string Name = "";
|            public List<string> Names = new List<string>();
|            public List<string> Types = new List<string>();
|            public bool ColumnsDone;
|            public bool Keep = true;
|            public ConstructorInfo Ctor;
|            public bool CtorAsked;
|            public Dictionary<string, string> Pool;
|            public List<object> Rows = new List<object>();
|            public List<string[]> Early;   // rows met before the column list (kept as values, built at the end)
|            public Func<string[], string[], object> Plain;   // names that differ only in case: the row is built as the lean read builds it
|            public bool PlainChecked;
|        }
|
|        private static LaStreamAnswer ReadCore(Stream stream, bool compact, Func<string[], ConstructorInfo> compactCtorFor, int bufferSize, Func<string[], string[], object> plainRowFor, PageSink sink)
|        {
|            if (stream == null) throw new ArgumentNullException("stream");
|            byte[] buf = new byte[Math.Max(1024, bufferSize)];
|            int filled = 0, start = 0;
|            bool final = false;
|            long total = 0;
|            int largest = buf.Length;
|            JsonReaderState state = new JsonReaderState();
|            var stack = new List<Ctx>();
|            string prop = null;
|            TableAcc cur = null, first = null, primary = null;
|            int tableCount = 0;
|            string errorJson = null;
|            bool bomChecked = false;
|
|            while (true)
|            {
|                // fill: keep what is not consumed, grow only when one unit does not fit
|                if (start > 0) { Buffer.BlockCopy(buf, start, buf, 0, filled - start); filled -= start; start = 0; }
|                if (!final)
|                {
|                    if (filled == buf.Length)
|                    {
|                        var bigger = new byte[buf.Length * 2]; Buffer.BlockCopy(buf, 0, bigger, 0, filled); buf = bigger;
|                        if (buf.Length > largest) largest = buf.Length;
|                    }
|                    int n = stream.Read(buf, filled, buf.Length - filled);
|                    if (n <= 0) final = true; else { filled += n; total += n; }
|                    if (!bomChecked && (filled >= 3 || final))
|                    {
|                        bomChecked = true;
|                        if (filled >= 3 && buf[0] == 0xEF && buf[1] == 0xBB && buf[2] == 0xBF) start = 3;
|                    }
|                    if (!final && filled < buf.Length && n > 0) continue;   // read until the buffer is full or the stream ends
|                }
|
|                var reader = new Utf8JsonReader(new ReadOnlySpan<byte>(buf, start, filled - start), final, state);
|                bool more = false;
|                while (true)
|                {
|                    JsonReaderState before = reader.CurrentState;
|                    long beforeAt = reader.BytesConsumed;
|                    if (!reader.Read()) { more = true; break; }
|                    JsonTokenType tt = reader.TokenType;
|                    Ctx ctx = stack.Count == 0 ? Ctx.Root : stack[stack.Count - 1];
|                    if (stack.Count == 0)
|                    {
|                        if (tt == JsonTokenType.StartObject) { stack.Add(Ctx.Root); continue; }
|                        throw new JsonException("the Log Analytics answer is not a JSON object");
|                    }
|                    if (tt == JsonTokenType.PropertyName) { prop = reader.GetString(); continue; }
|
|                    // a UNIT: a value that is read whole (a row, a column, the error, anything skipped) -- its bytes must all be
|                    // in the buffer; when they are not, everything goes back to before its first token and more is read
|                    bool container = (tt == JsonTokenType.StartObject || tt == JsonTokenType.StartArray);
|                    switch (ctx)
|                    {
|                        case Ctx.Root:
|                            if (tt == JsonTokenType.EndObject) { stack[stack.Count - 1] = Ctx.Done; continue; }
|                            if (prop == "tables" && tt == JsonTokenType.StartArray) { stack.Add(Ctx.Tables); prop = null; continue; }
|                            {
|                                int us = start + (int)reader.TokenStartIndex;
|                                if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                                int ue = start + (int)reader.BytesConsumed;
|                                if (prop == "error")
|                                {
|                                    errorJson = (tt == JsonTokenType.Null) ? null : Encoding.UTF8.GetString(buf, us, ue - us);
|                                }
|                                prop = null;
|                                continue;
|                            }
|                        case Ctx.Tables:
|                            if (tt == JsonTokenType.EndArray) { stack.RemoveAt(stack.Count - 1); continue; }
|                            if (tt == JsonTokenType.StartObject)
|                            {
|                                cur = new TableAcc { Index = tableCount++, Plain = plainRowFor };
|                                // a later table's rows are kept only while no PrimaryResult was found before it
|                                cur.Keep = (primary == null);
|                                if (compact) cur.Pool = new Dictionary<string, string>(StringComparer.Ordinal);
|                                stack.Add(Ctx.Table); prop = null; continue;
|                            }
|                            if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                            continue;
|                        case Ctx.Table:
|                            if (tt == JsonTokenType.EndObject)
|                            {
|                                stack.RemoveAt(stack.Count - 1);
|                                FinishTable(cur, compact, compactCtorFor);
|                                if (sink != null && object.ReferenceEquals(sink.Table, cur)) Flush(sink, cur.Rows);
|                                if (cur.Index == 0) first = cur;
|                                if (primary == null && cur.Name == "PrimaryResult") { primary = cur; if (first != null && first != cur) first.Rows = null; }
|                                else if (cur.Index != 0) cur.Rows = null;
|                                cur = null; prop = null; continue;
|                            }
|                            if (prop == "name" && !container)
|                            {
|                                cur.Name = (tt == JsonTokenType.String) ? (reader.GetString() ?? "") : "";
|                                prop = null; continue;
|                            }
|                            if (prop == "columns" && tt == JsonTokenType.StartArray) { stack.Add(Ctx.Columns); prop = null; continue; }
|                            if (prop == "rows" && tt == JsonTokenType.StartArray) { stack.Add(Ctx.Rows); prop = null; continue; }
|                            if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                            prop = null; continue;
|                        case Ctx.Columns:
|                            if (tt == JsonTokenType.EndArray) { stack.RemoveAt(stack.Count - 1); cur.ColumnsDone = true; continue; }
|                            {
|                                int us = start + (int)reader.TokenStartIndex;
|                                if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                                int ue = start + (int)reader.BytesConsumed;
|                                if (tt == JsonTokenType.StartObject) ReadColumn(buf, us, ue - us, cur);
|                                continue;
|                            }
|                        case Ctx.Rows:
|                            if (tt == JsonTokenType.EndArray) { stack.RemoveAt(stack.Count - 1); continue; }
|                            {
|                                int us = start + (int)reader.TokenStartIndex;
|                                if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                                int ue = start + (int)reader.BytesConsumed;
|                                if (tt == JsonTokenType.StartArray && cur.Keep)
|                                {
|                                    if (sink == null) AddRow(buf, us, ue - us, cur, compact, compactCtorFor);
|                                    else if (SinkTakes(sink, cur))
|                                    {
|                                        AddRow(buf, us, ue - us, cur, compact, compactCtorFor);
|                                        sink.Bytes += (ue - us);
|                                        if (sink.Bytes >= sink.Limit) Flush(sink, cur.Rows);
|                                    }
|                                }
|                                continue;
|                            }
|                        default:
|                            if (container && !reader.TrySkip()) { state = before; start += (int)beforeAt; more = true; goto Refill; }
|                            continue;
|                    }
|                }
|                state = reader.CurrentState;
|                start += (int)reader.BytesConsumed;
|            Refill:
|                if (final)
|                {
|                    if (stack.Count == 0 || stack[0] != Ctx.Done) throw new JsonException("the Log Analytics answer ended before it was complete");
|                    break;
|                }
|                if (!more) continue;
|            }
|
|            TableAcc pick = primary ?? first;
|            var ans = new LaStreamAnswer { ErrorJson = errorJson, BytesRead = total, LargestBuffer = largest };
|            if (sink != null) { ans.RowsDelivered = sink.Rows; ans.Pages = sink.Pages; }
|            if (pick != null)
|            {
|                ans.Rows = (pick.Rows == null || sink != null) ? new object[0] : pick.Rows.ToArray();
|                ans.ColumnNames = pick.Names.ToArray();
|                ans.ColumnTypes = pick.Types.ToArray();
|            }
|            else { ans.Rows = new object[0]; ans.ColumnNames = new string[0]; ans.ColumnTypes = new string[0]; }
|            return ans;
|        }
|
|        // with a page callback: does this table's row go to the pages? The table named PrimaryResult, else the first table --
|        // as the whole read picks it. A PrimaryResult that comes after another table's rows were handed on cannot be read in
|        // pages (those rows are gone): the read fails, never a wrong set handed on.
|        private static bool SinkTakes(PageSink sink, TableAcc cur)
|        {
|            if (object.ReferenceEquals(sink.Table, cur)) return true;
|            if (sink.Table == null)
|            {
|                if (cur.Name == "PrimaryResult" || cur.Index == 0) { sink.Table = cur; sink.FromNonPrimary = (cur.Name != "PrimaryResult"); return true; }
|                return false;
|            }
|            if (cur.Name == "PrimaryResult" && sink.FromNonPrimary)
|            {
|                if (sink.Rows > 0) throw new InvalidOperationException("the Log Analytics answer names its primary table after another table whose rows were already handed on -- it cannot be read in pages");
|                ((TableAcc)sink.Table).Rows.Clear();
|                sink.Table = cur; sink.FromNonPrimary = false; sink.Bytes = 0;
|                return true;
|            }
|            return false;
|        }
|
|        private static void ReadColumn(byte[] buf, int off, int len, TableAcc t)
|        {
|            var r = new Utf8JsonReader(new ReadOnlySpan<byte>(buf, off, len), true, new JsonReaderState());
|            r.Read();   // StartObject
|            string name = null, type = null; bool hasName = false;
|            while (r.Read())
|            {
|                if (r.TokenType == JsonTokenType.EndObject && r.CurrentDepth == 0) break;
|                if (r.TokenType != JsonTokenType.PropertyName) continue;
|                string p = r.GetString();
|                r.Read();
|                if (r.TokenType == JsonTokenType.StartObject || r.TokenType == JsonTokenType.StartArray) { r.Skip(); continue; }
|                if (p == "name") { name = (r.TokenType == JsonTokenType.String || r.TokenType == JsonTokenType.Null) ? r.GetString() : Encoding.UTF8.GetString(r.ValueSpan.ToArray()); hasName = true; }
|                else if (p == "type") { type = (r.TokenType == JsonTokenType.String || r.TokenType == JsonTokenType.Null) ? r.GetString() : Encoding.UTF8.GetString(r.ValueSpan.ToArray()); }
|            }
|            if (!hasName) throw new KeyNotFoundException("a column of the Log Analytics answer has no name");
|            t.Names.Add(name); t.Types.Add(type);
|        }
|
|        private static string[] ReadCells(byte[] buf, int off, int len, int nCols, Dictionary<string, string> pool)
|        {
|            var r = new Utf8JsonReader(new ReadOnlySpan<byte>(buf, off, len), true, new JsonReaderState());
|            r.Read();   // StartArray
|            var cells = nCols >= 0 ? new string[nCols] : null;
|            var open = nCols < 0 ? new List<string>() : null;
|            int i = 0;
|            while (r.Read())
|            {
|                if (r.TokenType == JsonTokenType.EndArray && r.CurrentDepth == 0) break;
|                string s;
|                switch (r.TokenType)
|                {
|                    case JsonTokenType.String: s = r.GetString(); break;
|                    case JsonTokenType.Null: s = null; break;
|                    case JsonTokenType.True: s = "true"; break;
|                    case JsonTokenType.False: s = "false"; break;
|                    case JsonTokenType.StartObject:
|                    case JsonTokenType.StartArray:
|                        {
|                            int ts = (int)r.TokenStartIndex;
|                            r.Skip();
|                            s = Encoding.UTF8.GetString(buf, off + ts, (int)r.BytesConsumed - ts);
|                            break;
|                        }
|                    default: s = Encoding.UTF8.GetString(r.ValueSpan.ToArray()); break;
|                }
|                if (s != null && pool != null && s.Length <= 32)
|                {
|                    string p0;
|                    if (pool.TryGetValue(s, out p0)) s = p0; else pool[s] = s;
|                }
|                if (open != null) open.Add(s);
|                else if (i < nCols) cells[i] = s;
|                i++;
|            }
|            return open != null ? open.ToArray() : cells;
|        }
|
|        private static object MakeRow(string[] cells, TableAcc t)
|        {
|            if (t.Ctor != null) return t.Ctor.Invoke(new object[] { cells });
|            if (!t.PlainChecked)
|            {
|                t.PlainChecked = true;
|                var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase); bool dup = false;
|                foreach (var nm in t.Names) { if (nm != null && !seen.Add(nm)) { dup = true; break; } }
|                if (!dup) t.Plain = null;
|            }
|            if (t.Plain != null) return t.Plain(t.Names.ToArray(), cells);
|            var o = new PSObject();
|            int n = t.Names.Count;
|            for (int i = 0; i < n; i++)
|            {
|                string v = i < cells.Length ? cells[i] : null;
|                var existing = o.Properties[t.Names[i]];
|                if (existing != null) existing.Value = v; else o.Properties.Add(new PSNoteProperty(t.Names[i], v));
|            }
|            return o;
|        }
|
|        private static void AddRow(byte[] buf, int off, int len, TableAcc t, bool compact, Func<string[], ConstructorInfo> compactCtorFor)
|        {
|            if (!t.ColumnsDone && t.Names.Count == 0)
|            {
|                if (t.Early == null) t.Early = new List<string[]>();
|                t.Early.Add(ReadCells(buf, off, len, -1, null));
|                return;
|            }
|            if (compact && !t.CtorAsked) { MakeRowPrepare(t, compactCtorFor); }
|            var cells = ReadCells(buf, off, len, t.Names.Count, t.Ctor != null ? t.Pool : null);
|            t.Rows.Add(MakeRow(cells, t));
|        }
|
|        private static void MakeRowPrepare(TableAcc t, Func<string[], ConstructorInfo> compactCtorFor)
|        {
|            // the compact type for these columns, asked once; none -> PSCustomObject rows without pooling, as the lean read
|            t.CtorAsked = true;
|            if (compactCtorFor != null) t.Ctor = compactCtorFor(t.Names.ToArray());
|            if (t.Ctor == null) t.Pool = null;
|        }
|
|        private static void FinishTable(TableAcc t, bool compact, Func<string[], ConstructorInfo> compactCtorFor)
|        {
|            if (t.Early == null) return;
|            if (!t.Keep) { t.Early = null; return; }
|            var built = new List<object>(t.Early.Count + t.Rows.Count);
|            if (compact && !t.CtorAsked) MakeRowPrepare(t, compactCtorFor);
|            int n = t.Names.Count;
|            foreach (var raw in t.Early)
|            {
|                var cells = new string[n];
|                for (int i = 0; i < n && i < raw.Length; i++) cells[i] = raw[i];
|                built.Add(MakeRow(cells, t));
|            }
|            built.AddRange(t.Rows);
|            t.Rows = built; t.Early = null;
|        }
|    }
|}
|'@
|}
|
|function Get-SILaStreamReaderType {
|    <# The compiled reader ([SecurityInsight.LaStream.LaStreamReader]), built once per process; $null where it cannot be
|       (Windows PowerShell, or a compile that fails -- the caller then keeps the lean read). Scope-independent (#836): the
|       compiled type is found by its NAME (a type is per process), the source comes from a function, and a compile that
|       failed is remembered for the whole process in $global:SI_LaStreamReaderOff (its reason) -- tried once, not per read. #>
|    if ($PSVersionTable.PSEdition -ne 'Core') { return $null }
|    # off for this process (it could not be built, or it failed on an answer -- Read-SILaQueryStreamSafe): the older read
|    if ($global:SI_LaStreamReaderOff) { return $null }
|    $t = 'SecurityInsight.LaStream.LaStreamReader' -as [type]
|    if ($null -ne $t) { return $t }
|    try {
|        $src = Get-SILaStreamReaderSource
|        if ([string]::IsNullOrWhiteSpace([string]$src)) { throw 'its source is empty' }
|        Add-Type -TypeDefinition $src -Language CSharp -ErrorAction Stop
|        $t = 'SecurityInsight.LaStream.LaStreamReader' -as [type]
|        if ($null -eq $t) { throw 'the compiled type was not found' }
|        return $t
|    } catch {
|        $global:SI_LaStreamReaderOff = 'the reader could not be built in this process: ' + (Get-SILaStreamShortReason $_.Exception.Message)
|        return $null
|    }
|}
|
|function Get-SILaStreamShortReason {
|    <# PURE. The first line of an error text, at most 300 characters (a compiler error lists every line it refused). #>
|    param([AllowNull()][AllowEmptyString()][string]$Text)
|    $s = ([string]$Text -split "`r?`n" | Where-Object { $_.Trim() } | Select-Object -First 1)
|    if (-not $s) { return 'no reason given' }
|    $s = $s.Trim()
|    if ($s.Length -gt 300) { $s = $s.Substring(0, 300) + ' ...' }
|    return $s
|}
|
|function Write-SILaStreamFallback {
|    <#
|        #836: the older read is used instead of the streaming one -- ONE plain line on the run log (the transcript) saying
|        so and why. -Once: said once per process for that reason (the reader cannot be built: every later read is the
|        older one too, and saying it per read would flood the log). Without -Once (one read whose stream failed and was
|        read again the older way) it is said every time it happens. The results are the same either way.
|    #>
|    param([AllowNull()][AllowEmptyString()][string]$Reason, [switch]$Once)
|    if ([string]::IsNullOrWhiteSpace($Reason)) { $Reason = 'the streaming reader is not available in this process' }
|    if ($Once) {
|        if ($null -eq $global:SI_LaStreamFallbackSaid) { $global:SI_LaStreamFallbackSaid = @{} }
|        if ($global:SI_LaStreamFallbackSaid.ContainsKey($Reason)) { return }
|        $global:SI_LaStreamFallbackSaid[$Reason] = $true
|    }
|    Write-Host ('Log Analytics answers are read the older way (whole, then parsed) instead of as they arrive -- {0}. The rows are the same; the read uses more memory.' -f $Reason) -ForegroundColor DarkYellow
|}
|
|function Read-SILaQueryStreamSafe {
|    <#
|        #836: ConvertFrom-SILaQueryStream for Invoke-SILaQuery's -ReadStream -- DATA FIRST: a read that fails (the reader
|        throws, the answer is not valid JSON, the connection drops mid-answer) is NOT an error of the query: it answers a
|        marker (.SILaStreamFailed = why) and Invoke-SILaQuery reads the same query again the older way and says so in one
|        line. A failure that is not the network's (IOException / a socket error) turns streaming off for the rest of the
|        process ($global:SI_LaStreamReaderOff) so a reader fault never doubles every read.
|    #>
|    param([Parameter(Mandatory)][System.IO.Stream]$Stream, [switch]$Compact,
|          # the rows a page at a time (ConvertFrom-SILaQueryStream -OnPage); -PageState counts the pages handed on so far
|          [scriptblock]$OnPage, [long]$PageBytes = 4MB, [hashtable]$PageState)
|    try {
|        if ($OnPage) { return (ConvertFrom-SILaQueryStream -Stream $Stream -Compact:$Compact -OnPage $OnPage -PageBytes $PageBytes -PageState $PageState) }
|        return (ConvertFrom-SILaQueryStream -Stream $Stream -Compact:$Compact)
|    }
|    catch {
|        $ex = $_.Exception
|        # the CALLER's page callback failed (a page could not be stored): its own failure, passed on as it is -- never a
|        # reader fault, never read again
|        for ($e = $ex; $null -ne $e; $e = $e.InnerException) {
|            if ($e.GetType().FullName -eq 'SecurityInsight.LaStream.LaStreamPageException') {
|                $cause = $e.InnerException
|                while ($cause -is [System.Management.Automation.MethodInvocationException] -and $null -ne $cause.InnerException) { $cause = $cause.InnerException }
|                if ($cause -is [System.Management.Automation.RuntimeException] -and $cause.ErrorRecord) { throw $cause.ErrorRecord }
|                if ($null -ne $cause) { throw $cause }
|                throw $e
|            }
|        }
|        $net = $false
|        for ($e = $ex; $null -ne $e; $e = $e.InnerException) {
|            if ($e -is [System.IO.IOException] -or $e -is [System.Net.WebException] -or $e -is [System.Net.Sockets.SocketException]) { $net = $true; break }
|        }
|        $inner = $ex; while ($null -ne $inner.InnerException) { $inner = $inner.InnerException }
|        $why = Get-SILaStreamShortReason $inner.Message
|        if (-not $net) { $global:SI_LaStreamReaderOff = 'the streaming reader failed on an answer: ' + $why }
|        return [pscustomobject]@{ SILaStreamFailed = $why; Network = $net }
|    }
|}
|
|function ConvertFrom-SILaQueryStream {
|    <#
|        The Log Analytics query response READ FROM ITS STREAM -> @{ Rows; Columns; Error } -- the shape and the rows of
|        ConvertFrom-SILaQueryRows (SI-AzRest.ps1), without the answer ever being held whole. -Compact: compact rows
|        (Get-SILaCompactRowType) where a compact type can be built for the columns; PSCustomObject rows otherwise.
|        -BufferBytes: the first buffer (it grows only when one row does not fit). Throws on an answer that is not valid
|        JSON or ends early (as the lean read does).
|        -OnPage { param($Rows) }: FOR EVERY READER, not only Risk Analysis -- the primary table's rows are handed on a page
|        at a time, as soon as about -PageBytes of the answer's own bytes are in, and are never collected: memory is one
|        page. .Rows is then empty; .RowCount / .Pages say what was handed on; -PageState (a hashtable) is kept up to date
|        as pages go out (Pages, Rows). The error object (a cut answer) comes at the END of the answer, after the pages: a
|        caller keeps its pages only once the whole read returned (Invoke-SILaQuery -OnPage refuses a cut answer there).
|    #>
|    param([Parameter(Mandatory)][System.IO.Stream]$Stream, [switch]$Compact, [int]$BufferBytes = 65536,
|          [scriptblock]$OnPage, [long]$PageBytes = 4MB, [hashtable]$PageState)
|    $t = Get-SILaStreamReaderType
|    if ($null -eq $t) { throw 'the streaming Log Analytics reader is not available in this process' }
|    $ctorFor = $null
|    if ($Compact) {
|        $ctorFor = [Func[string[], System.Reflection.ConstructorInfo]] {
|            param([string[]]$names)
|            $ct = $null
|            if (Get-Command -Name Get-SILaCompactRowType -ErrorAction SilentlyContinue) { $ct = Get-SILaCompactRowType -Names $names }
|            if ($null -eq $ct) { return $null }
|            return $ct.GetConstructor([type[]]@([string[]]))
|        }
|    }
|    # column names that differ only in case (never in a real answer): the row is built exactly as the lean read builds it
|    # [[string[]]] -- the spelling Windows PowerShell 5.1 can parse too: setup scripts a customer runs there load this file
|    # through SI-AzRest.ps1 (the same type as [Func[string[], string[], object]], which 5.1 refuses as a parse error)
|    $plainFor = [Func[[string[]], [string[]], object]] {
|        param([string[]]$names, [string[]]$cells)
|        $o = [ordered]@{}
|        for ($i = 0; $i -lt $names.Length; $i++) { $o[$names[$i]] = $(if ($i -lt $cells.Length) { $cells[$i] } else { $null }) }
|        [pscustomobject]$o
|    }
|    if ($OnPage) {
|        if ($null -eq $PageState) { $PageState = @{} }
|        $PageState['Pages'] = 0; $PageState['Rows'] = 0L
|        $__psOn = $OnPage; $__psState = $PageState
|        $pageAction = [Action[object[]]] {
|            param([object[]]$page)
|            $null = & $__psOn $page
|            $__psState['Pages'] = [int]$__psState['Pages'] + 1
|            $__psState['Rows'] = [long]$__psState['Rows'] + $page.Length
|        }
|        $a = $t::Read($Stream, [bool]$Compact, $ctorFor, $BufferBytes, $plainFor, $pageAction, [long]$PageBytes)
|    } else {
|        $a = $t::Read($Stream, [bool]$Compact, $ctorFor, $BufferBytes, $plainFor)
|    }
|    $cols = [System.Collections.Generic.List[object]]::new()
|    for ($i = 0; $i -lt $a.ColumnNames.Length; $i++) { $cols.Add([pscustomobject]@{ name = $a.ColumnNames[$i]; type = $a.ColumnTypes[$i] }) }
|    $err = $null
|    if ($null -ne $a.ErrorJson) { $err = ($a.ErrorJson | ConvertFrom-Json) }
|    $count = [long]$a.Rows.Length; if ($OnPage) { $count = [long]$a.RowsDelivered }
|    # (#836: $global:, never $script: -- a function's $script: is its caller's)
|    $global:SI_LaStreamLast = [pscustomobject]@{ BytesRead = $a.BytesRead; LargestBuffer = $a.LargestBuffer; Rows = $count; Pages = [int]$a.Pages }
|    return [pscustomobject]@{ Rows = $a.Rows; Columns = $cols.ToArray(); Error = $err; RowCount = $count; Pages = [int]$a.Pages }
|}
'@ }
$__siSupportFiles['engine/_shared/SI-LaParts.ps1'] = @{ Sha256 = 'd6068eb409f171257cf45624fee0eea678cadb739bc63f8b366afc3f9b7b1edd'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- a Log Analytics read IN PARTS, so a large install never meets the service's limit on one answer
|    (#639 lane 4, owner 2026-10-21: "memory issues must not be a problem in any step. env must work in millions of assets
|    env"). Loaded by SI-AzRest.ps1, and guarded by every caller, so it loads on its own (tests).
|
|    WHY. One Log Analytics answer carries at most ~500,000 rows / ~64 MB. Invoke-SILaQuery REFUSES an answer the service
|    cut (New-SILaCutAnswerError) -- a cut answer is never taken as whole. A reader whose result can outgrow one answer
|    (a profile snapshot, the correlation map, a customer's rule query) therefore reads in PARTS:
|
|      * The query is first asked AS IT IS -- a small result costs exactly what it cost before (one query, unchanged).
|      * Refused as cut (or too large, or this process ran out of memory on it): the query is MEASURED once (rows and
|        bytes of its result) and read again in that many parts: each part is the query's own result, filtered on a hash
|        of each result row (or of a key the caller names). The parts never overlap and together are every row --
|        whatever the query does, because the filter is applied to its RESULT.
|      * A part still refused is cut in two (only that part; on a hash of its own, so the pieces never overlap); a part
|        far larger than planned cuts every part still to read by the measured factor. The size of a part follows what
|        was measured, never a fixed number (working rule 5).
|      * MEASURED stop, never a cap: a refused part that held NO row at all, twice in a row, is the query's own work
|        hitting a limit (every part repeats it) -- more parts cannot help, and the read fails saying so.
|      * A part that fails for any other reason fails THE READ: what was read is not the whole, so it is UNKNOWN -- never
|        handed out as the result (working rule 4). The caller's own handling of a failed read applies unchanged.
|
|    A query whose rows differ between two runs of it (take / limit / sample) is never cut into parts: its refusal is passed
|    on as it is. The rows of a read in parts come in no particular order.
|
|    PowerShell 5.1-safe: no ternary, no null-conditional. NO Set-StrictMode here (it leaks into the caller's scope).
|    A caller's -Read / -OnRows / -Log block runs INSIDE Read-SILaParts: a variable it reads must not share a name with
|    this function's own (Query, WorkspaceId, Wait, Key, Read, OnRows, What, Log, rows, got, page, queue ...).
|#>
|
|# Azure access: plain REST, no PowerShell modules (SI-AzRest.ps1 loads this file last, so this never loads it twice).
|if (-not (Get-Command -Name Invoke-SIArm -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot './SI-AzRest.ps1') }
|
|function Get-SILaPartFilter {
|    <#
|        PURE. The KQL that keeps ONE part of a query's result: -Cuts = @( @{ Parts; Part } ...) -- the first cut is the
|        planned part ("bucket Part of Parts" of the row's hash); each later cut divides that part again on a hash of its own
|        (the depth in front of the value), so the pieces of a part never overlap and together are that part. -Key: a KQL
|        expression on the result's columns to hash (e.g. 'SI_AssetId'); '' = the whole result row (pack_all()). '' = no cut.
|    #>
|    param([AllowNull()][AllowEmptyCollection()][object[]]$Cuts = @(), [string]$Key = '')
|    $terms = New-Object System.Collections.Generic.List[string]
|    for ($d = 0; $d -lt @($Cuts).Count; $d++) {
|        $parts = [long]$Cuts[$d].Parts; $part = [long]$Cuts[$d].Part
|        if ($parts -lt 1 -or $part -lt 0 -or $part -ge $parts) { throw ('Get-SILaPartFilter: part {0} is outside 0..{1}' -f $part, ($parts - 1)) }
|        if ($parts -eq 1) { continue }
|        if ($d -eq 0) { $terms.Add(('hash(_siPart, {0}) == {1}' -f $parts, $part)) }
|        else { $terms.Add(('hash(strcat("{0}|", _siPart), {1}) == {2}' -f $d, $parts, $part)) }
|    }
|    if ($terms.Count -eq 0) { return '' }
|    $k = 'tostring(pack_all())'
|    if ($Key) { $k = 'tostring({0})' -f $Key }
|    ('| extend _siPart = {0} | where {1} | project-away _siPart' -f $k, ($terms -join ' and '))
|}
|
|function Get-SILaPartQuery {
|    <#
|        PURE. -Query with -Filter after its LAST tabular statement: trailing blank / comment lines and semicolons are taken
|        off first, so the filter follows the result. '' -Filter = the query unchanged.
|    #>
|    param([Parameter(Mandatory)][string]$Query, [AllowEmptyString()][string]$Filter = '')
|    if (-not $Filter) { return $Query }
|    $lines = New-Object System.Collections.Generic.List[string]
|    foreach ($l in ($Query -split "`r?`n")) { $lines.Add($l) }
|    while ($lines.Count -gt 0) {
|        $t = $lines[$lines.Count - 1].Trim()
|        if ($t -eq '' -or $t.StartsWith('//')) { $lines.RemoveAt($lines.Count - 1); continue }
|        if ($t.EndsWith(';')) { $lines[$lines.Count - 1] = $lines[$lines.Count - 1].TrimEnd().TrimEnd(';'); continue }
|        break
|    }
|    (($lines -join "`n") + "`n" + $Filter)
|}
|
|function Get-SILaMeasureQuery {
|    <# PURE. How many rows -Query's result holds and about how many bytes (one small answer: SIRows, SIBytes). #>
|    param([Parameter(Mandatory)][string]$Query)
|    Get-SILaPartQuery -Query $Query -Filter '| summarize SIRows = count(), SIBytes = sum(estimate_data_size(*))'
|}
|
|function Test-SILaQueryPartable {
|    <# PURE. May -Query be read in parts? Not when its rows differ between two runs of it (take / limit / sample): the parts
|       of two runs would not be one result. #>
|    param([AllowEmptyString()][string]$Query)
|    -not ([string]$Query -match '(?im)\|\s*(take|limit|sample|sample-distinct)\b')
|}
|
|function Get-SILaPartFailure {
|    <#
|        PURE. What a failed read of one part says: @{ Cut = $true when a SMALLER part fixes it -- an answer the service cut
|        for a limit (Invoke-SILaQuery's refusal, Risk Analysis' own), an answer refused as too large, or this process out of
|        memory on it; Rows = the rows the short answer held (-1 unknown) }. Anything else: Cut = $false (passed on as it is).
|    #>
|    param([AllowNull()][object]$Err)
|    $ex = $null; $texts = New-Object System.Collections.Generic.List[string]
|    if ($Err -is [System.Management.Automation.ErrorRecord]) {
|        $ex = $Err.Exception
|        if ($Err.ErrorDetails -and $Err.ErrorDetails.Message) { $texts.Add([string]$Err.ErrorDetails.Message) }
|    } elseif ($Err -is [System.Exception]) { $ex = $Err }
|    elseif ($null -ne $Err) { $texts.Add([string]$Err) }
|    $e = $ex
|    while ($null -ne $e) {
|        if ($e -is [System.OutOfMemoryException] -or $e -is [System.InsufficientExecutionStackException]) { return @{ Cut = $true; Rows = -1L; Why = 'too large for this job''s memory' } }
|        if ($e.Data) {
|            foreach ($k in 'SILaPartial', 'SIRALaPartial') {
|                if ($e.Data.Contains($k)) {
|                    $rows = -1L
|                    if ($e.Data.Contains('SIRALaPartialRows')) { try { $rows = [long]$e.Data['SIRALaPartialRows'] } catch { $rows = -1L } }
|                    return @{ Cut = ([string]$e.Data[$k] -eq 'Limit'); Rows = $rows; Why = 'cut by the service''s limit' }
|                }
|            }
|        }
|        $texts.Add([string]$e.Message)
|        try { if ($e.PSObject.Properties['Response'] -and $e.Response -and $e.Response.PSObject.Properties['Content']) { $texts.Add([string]$e.Response.Content) } } catch { }
|        $e = $e.InnerException
|    }
|    $all = ($texts -join ' ')
|    if ($all -match '(?i)E_QUERY_RESULT_SET_TOO_LARGE|ResponsePayloadTooLarge|ResponseSizeError|result set (is )?too large|exceeds? the (maximum )?(response|result) size|response size .*exceed') {
|        return @{ Cut = $true; Rows = -1L; Why = 'too large to read in one answer' }
|    }
|    @{ Cut = $false; Rows = -1L; Why = '' }
|}
|
|function ConvertTo-SILaPartRows {
|    <# PURE. Rows however a reader handed them over -- one array (`, @(rows)`), an array holding that array, or rows on the
|       pipeline -- as ONE flat object[] without nulls. #>
|    param([AllowNull()][object]$Answer)
|    $l = New-Object System.Collections.Generic.List[object]
|    foreach ($x in @($Answer)) {
|        if ($null -eq $x) { continue }
|        if ($x -is [array]) { foreach ($y in $x) { if ($null -ne $y) { $l.Add($y) } } } else { $l.Add($x) }
|    }
|    , $l.ToArray()
|}
|
|function Get-SILaPartPlan {
|    <#
|        PURE. How many parts a result of -Rows rows / about -Bytes bytes is read in: each part well under one answer's
|        limits -- at most half the service's own row limit, and -TargetBytes of answer (the JSON answer is -Expansion times
|        the data's own size). At least 2 (the result was refused whole). Follows the measurement; no ceiling.
|    #>
|    param([long]$Rows = -1, [double]$Bytes = -1, [long]$TargetRows = 0, [double]$TargetBytes = 16MB, [double]$Expansion = 2.5)
|    if ($TargetRows -le 0) {
|        $limit = 500000L
|        if (Get-Command -Name Get-SILaServiceRowLimit -ErrorAction SilentlyContinue) { $limit = [long](Get-SILaServiceRowLimit) }
|        $TargetRows = [long][Math]::Max(1, [Math]::Floor($limit / 2))
|    }
|    $n = 2L
|    if ($Rows -gt 0) { $n = [long][Math]::Max($n, [Math]::Ceiling([double]$Rows / [double]$TargetRows)) }
|    if ($Bytes -gt 0 -and $TargetBytes -gt 0) { $n = [long][Math]::Max($n, [Math]::Ceiling(($Bytes * $Expansion) / $TargetBytes)) }
|    $n
|}
|
|function Read-SILaParts {
|    <#
|        ONE Log Analytics read, in parts when one answer cannot carry it (see the header of this file). Every row once.
|          -Query      the KQL (asked as it is first)
|          -Key        a KQL expression on the result's columns that the parts hash on ('' = the whole result row). A key
|                      that is the same for many rows cannot divide them -- '' always can.
|          -Read       { param($Kql) rows } -- the reader (the seam for tests). Default: Invoke-SIAzOperationalInsightsQuery
|                      on -WorkspaceId (with -Wait), its .Results.
|          -OnRows     { param($Rows) } -- each part's rows as soon as that part is read whole (then not collected; memory is
|                      one part). The parts handed on are only the result when this call RETURNS: a later part that fails
|                      throws, and the caller treats the whole read as failed. Without -OnRows the rows are collected.
|          -What       what is read, for the lines it says; -Log { param($Level, $Message) }
|        Returns @{ Rows (without -OnRows); RowCount; Pages; Parts (planned); Cuts }. Throws when the read is not whole.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$Query,
|        [string]$WorkspaceId = '',
|        [int]$Wait = 0,
|        [string]$Key = '',
|        [scriptblock]$Read,
|        [scriptblock]$OnRows,
|        [string]$What = 'the Log Analytics read',
|        [scriptblock]$Log,
|        [long]$TargetRows = 0,
|        [double]$TargetBytes = 16MB,
|        [int]$MaxDepth = 24
|    )
|    if (-not $Read) {
|        if (-not $WorkspaceId) { throw 'Read-SILaParts: -WorkspaceId or -Read is needed' }
|        # (-Wait only when given: the same call the readers made before, so a reader's own stand-in still answers it)
|        $Read = {
|            param($k)
|            $__p = @{ WorkspaceId = $WorkspaceId; Query = $k; ErrorAction = 'Stop' }
|            if ($Wait -gt 0) { $__p['Wait'] = $Wait }
|            $__a = Invoke-SIAzOperationalInsightsQuery @__p
|            if ($__a) { , @($__a.Results) } else { , @() }
|        }
|    }
|    if (-not $Log) { $Log = { param($l, $m) Write-Host ('[{0}] {1}' -f $l, $m) } }
|    if ($TargetRows -le 0) {
|        $limit = 500000L
|        if (Get-Command -Name Get-SILaServiceRowLimit -ErrorAction SilentlyContinue) { $limit = [long](Get-SILaServiceRowLimit) }
|        $TargetRows = [long][Math]::Max(1, [Math]::Floor($limit / 2))
|    }
|    $partable = Test-SILaQueryPartable -Query $Query
|    $acc = $null
|    if (-not $OnRows) { $acc = New-Object System.Collections.Generic.List[object] }
|    $queue = New-Object 'System.Collections.Generic.Queue[object]'
|    $queue.Enqueue([pscustomobject]@{ Cuts = @() })
|    $pages = 0L; $rowsRead = 0L; $cutsMade = 0L; $planned = 1L; $measured = $false; $emptyRefusals = 0
|    while ($queue.Count -gt 0) {
|        $page = $queue.Dequeue()
|        $kql = Get-SILaPartQuery -Query $Query -Filter (Get-SILaPartFilter -Cuts @($page.Cuts) -Key $Key)
|        $rows = $null; $fail = $null
|        try {
|            # assigned first: the reader answers ONE array (`, @(rows)`) -- @() around the call would hold it as one row
|            $got = & $Read $kql
|            $rows = ConvertTo-SILaPartRows $got
|            $got = $null
|        } catch {
|            $f = Get-SILaPartFailure -Err $_
|            if (-not $f.Cut -or -not $partable) { throw }
|            $fail = $f; $failErr = $_
|        }
|        if ($fail) {
|            $rows = $null
|            if (@($page.Cuts).Count -ge $MaxDepth) {
|                throw ('{0} is more than Log Analytics can answer: a part cut {1} times is still {2} -- the read is not whole and nothing of it is used' -f $What, @($page.Cuts).Count, $fail.Why)
|            }
|            if ([long]$fail.Rows -eq 0) { $emptyRefusals++ } else { $emptyRefusals = 0 }
|            if ($emptyRefusals -ge 2) {
|                throw ('{0} is more than Log Analytics can answer: a part stopped at the service''s limit before it returned a row, twice, so reading it in more parts cannot make it fit -- the read is not whole and nothing of it is used ({1})' -f $What, (([string]$failErr.Exception.Message -split "`n") | Select-Object -First 1))
|            }
|            if (@($page.Cuts).Count -eq 0 -and -not $measured) {
|                # the whole query was refused: measured ONCE, then read in that many parts
|                $measured = $true
|                $mRows = -1L; $mBytes = -1.0
|                try {
|                    $mr = ConvertTo-SILaPartRows (& $Read (Get-SILaMeasureQuery -Query $Query)); $m = $null; if ($mr.Count -gt 0) { $m = $mr[0] }
|                    if ($m) {
|                        if ($m.PSObject.Properties['SIRows'] -and "$($m.SIRows)" -ne '') { $mRows = [long][double]::Parse([string]$m.SIRows, [Globalization.CultureInfo]::InvariantCulture) }
|                        if ($m.PSObject.Properties['SIBytes'] -and "$($m.SIBytes)" -ne '') { $mBytes = [double]::Parse([string]$m.SIBytes, [Globalization.CultureInfo]::InvariantCulture) }
|                    }
|                } catch { $mRows = -1L; $mBytes = -1.0 }
|                $planned = Get-SILaPartPlan -Rows $mRows -Bytes $mBytes -TargetRows $TargetRows -TargetBytes $TargetBytes
|                for ($p = 0L; $p -lt $planned; $p++) { $queue.Enqueue([pscustomobject]@{ Cuts = @([pscustomobject]@{ Parts = $planned; Part = $p }) }) }
|                $cutsMade++
|                $sizeText = ''
|                if ($mRows -ge 0) { $sizeText = [string]::Format([Globalization.CultureInfo]::InvariantCulture, ' (measured: {0:N0} row(s){1})', $mRows, $(if ($mBytes -ge 0) { [string]::Format([Globalization.CultureInfo]::InvariantCulture, ', about {0:N0} MB', ($mBytes / 1MB)) } else { '' })) }
|                & $Log 'INFO' ('{0} is larger than one Log Analytics answer can carry ({1}) -- it is read in {2} parts{3}; nothing of the short answer is kept' -f $What, $fail.Why, $planned, $sizeText)
|            } else {
|                foreach ($half in 0, 1) { $queue.Enqueue([pscustomobject]@{ Cuts = @($page.Cuts) + @([pscustomobject]@{ Parts = 2L; Part = [long]$half }) }) }
|                $cutsMade++
|                & $Log 'INFO' ('{0}: a part was {1} -- it is read again in two smaller parts' -f $What, $fail.Why)
|            }
|            continue
|        }
|        $emptyRefusals = 0
|        $n = $rows.Count
|        $pages++; $rowsRead += $n
|        if ($OnRows) { $null = & $OnRows $rows } else { $acc.AddRange([object[]]$rows) }
|        $rows = $null
|        # measured, not assumed: a part far larger than planned -> every part still to read is cut by that factor
|        if (@($page.Cuts).Count -gt 0 -and $n -gt (2 * $TargetRows) -and $queue.Count -gt 0) {
|            $factor = [long][Math]::Ceiling([double]$n / [double]$TargetRows)
|            $rest = $queue.ToArray(); $queue.Clear()
|            foreach ($rp in $rest) { for ($piece = 0L; $piece -lt $factor; $piece++) { $queue.Enqueue([pscustomobject]@{ Cuts = @($rp.Cuts) + @([pscustomobject]@{ Parts = $factor; Part = $piece }) }) } }
|            $cutsMade++
|            & $Log 'INFO' ('{0}: its parts are larger than measured -- the {1} part(s) still to read are read as {2}' -f $What, $rest.Count, $queue.Count)
|        }
|    }
|    if ($pages -gt 1) { & $Log 'INFO' ([string]::Format([Globalization.CultureInfo]::InvariantCulture, '{0}: read whole in {1} part(s), {2:N0} row(s)', $What, $pages, $rowsRead)) }
|    $out = [ordered]@{ Rows = @(); RowCount = $rowsRead; Pages = $pages; Parts = $planned; Cuts = $cutsMade }
|    if ($acc) { $out.Rows = $acc.ToArray() }
|    [pscustomobject]$out
|}
'@ }
$__siSupportFiles['engine/_shared/SI-LogIngest.ps1'] = @{ Sha256 = '877c581ac6adda5fa7951afb09db3fefd7fbe77742dfbc686cf9037255224f6f'; Text = @'
|#Requires -Version 5.1
|<#
|    SI -- publish rows to a Log Analytics custom table through the normal DCR path.
|
|    Moved here from engine/asset-correlation/_shared/SI-CorrelationIngest.ps1 because a FREE stage uses
|    it too: the azure profiler's Defender for Cloud recommendations stage publishes with
|    Send-SIObjectMapRows. The correlation engine is part of SecurityInsight Pro and is not in the
|    Community edition, so a free engine must never load a file from its folder. The function names are
|    unchanged, so every caller and test keeps working.
|#>
|
|# NO Set-StrictMode HERE -- a dot-sourced file that sets it leaks into the caller's scope.
|
|# Azure access: plain REST, no PowerShell modules (engine/_shared/SI-AzRest.ps1).
|if (-not (Get-Command -Name Invoke-SIArm -ErrorAction Ignore)) { . (Join-Path $PSScriptRoot './SI-AzRest.ps1') }
|
|function Initialize-SIIngestGlobals {
|    <#
|      Fill the three names the DCR/DCE pinning and the LogIngest role grant need, from what an install
|      actually has (#174). The profiling orchestrator backfills them at its entry; the stages and engines that
|      publish WITHOUT it (trend, Defender recommendations, the Pro engines) did not -- and the CLI setup wrote
|      only the older names -- so pinning was skipped and a new DCR got no LogIngest principal.
|        SI_AzSubscriptionId  <- the subscription in SI_WorkspaceResourceId, else the 2.2.x SubscriptionId
|        SI_DceResourceGroup  <- the 2.2.x DceResourceGroup, else SI_DcrResourceGroup (same RG by default)
|        SI_SPN_ObjectId      <- SpnObjectId, else SI_LogIngest_ObjectId
|      Only EMPTY names are filled; a value the customer set always stands. Never throws.
|    #>
|    if (-not $global:SI_AzSubscriptionId) {
|        if ("$($global:SI_WorkspaceResourceId)" -match '/subscriptions/([^/]+)/') { $global:SI_AzSubscriptionId = $Matches[1] }
|        elseif ($global:SubscriptionId) { $global:SI_AzSubscriptionId = [string]$global:SubscriptionId }
|    }
|    if (-not $global:SI_DceResourceGroup) {
|        # SI_DcrResourceGroup FIRST: the unprefixed DceResourceGroup is ALWAYS set by the solution-wide shared
|        # defaults ('rg-dce-securityinsight'), so after loading it cannot tell a customer value from the default.
|        # The DCE normally lives with the DCRs (the sample: "leave unset, same RG as workspace").
|        if ($global:SI_DcrResourceGroup) { $global:SI_DceResourceGroup = [string]$global:SI_DcrResourceGroup }
|        elseif ($global:DceResourceGroup) { $global:SI_DceResourceGroup = [string]$global:DceResourceGroup }
|    }
|    if (-not $global:SI_SPN_ObjectId) {
|        if ($global:SpnObjectId) { $global:SI_SPN_ObjectId = [string]$global:SpnObjectId }
|        elseif ($global:SI_LogIngest_ObjectId) { $global:SI_SPN_ObjectId = [string]$global:SI_LogIngest_ObjectId }
|    }
|}
|
|function Get-SILogIngestObjectId {
|    <#
|      The object id that gets the ingest role on a new or updated data collection rule: SI_SPN_ObjectId (what setup
|      writes), else the older SI_LogIngest_ObjectId -- the same order Send-SIObjectMapRows, trend, asset properties and
|      the run-health row use. Three output stages passed SI_LogIngest_ObjectId alone, so an install with only
|      SI_SPN_ObjectId got a rule nobody could post to (#257). Empty when neither is set.
|    #>
|    if (-not [string]::IsNullOrWhiteSpace([string]$global:SI_SPN_ObjectId)) { return [string]$global:SI_SPN_ObjectId }
|    return [string]$global:SI_LogIngest_ObjectId
|}
|
|function Select-SIIngestTarget {
|    <#
|        #199 -- make the endpoint AzLogDcrIngestPS will use the RIGHT one, before it touches the rule and again
|        before the post. The module resolves the endpoint by NAME ONLY -- the first match in $global:AzDceDetails,
|        or in a tenant-wide Resource Graph query when that cache is empty. Measured 2026-10-01: three endpoints
|        named dce-securityinsight in two subscriptions; a rule created on the right one was re-bound to another
|        one minute later by the engine's own post (#198); four rules on this tenant were bound to the other
|        subscription's endpoint.
|        The endpoint is chosen as follows:
|          - a rule that EXISTS posts through the endpoint it is bound to, when that endpoint has the configured
|            name. Ingestion accepts a post only through the rule's own endpoint, and moving a rule is not an
|            option -- measured 2026-10-01, a re-bound rule was still refused (HTTP 403) more than 10 minutes later.
|          - otherwise (a new rule) this install's endpoint -- subscription + resource group + name -- so the
|            module creates the rule there and not on a same-named endpoint elsewhere.
|          - ONE endpoint of that name anywhere is unambiguous and used (an endpoint outside the rules' resource
|            group has always worked that way). Several and none here: refused, nothing is posted.
|        The DCR cache is narrowed to this install's rule (or, before it exists, cleared of same-named rules
|        elsewhere). An empty cache is built first. Without a subscription id there is nothing to pin to.
|    #>
|    param([hashtable]$AuthParams, [Parameter(Mandatory)][string]$DcrName)
|    $sub = [string]$global:SI_AzSubscriptionId
|    if (-not $sub -or -not $global:SI_DceName) { return }
|    $dceRg = if ($global:SI_DceResourceGroup) { [string]$global:SI_DceResourceGroup } else { [string]$global:SI_DcrResourceGroup }
|    $dcrRg = [string]$global:SI_DcrResourceGroup
|    $rebuilt = $false
|    $rebuild = {
|        if ($rebuilt -or -not $AuthParams) { return }
|        try { $global:AzDceDetails = Get-SIDceList @AuthParams -Verbose:$false 4>$null } catch { }
|        try { $global:AzDcrDetails = Get-SIDcrList @AuthParams -Verbose:$false 4>$null } catch { }
|        $rebuilt = $true   # dot-sourced: this IS the function's scope
|    }
|    $findHere = { @($global:AzDceDetails | Where-Object { $_ -and $_.name -eq $global:SI_DceName -and [string]$_.id -like "/subscriptions/$sub/resourceGroups/$dceRg/*" }) | Select-Object -First 1 }
|    $findRule = { if ($dcrRg) { @($global:AzDcrDetails | Where-Object { $_ -and $_.name -eq $DcrName -and [string]$_.id -like "/subscriptions/$sub/resourceGroups/$dcrRg/*" }) | Select-Object -First 1 } }
|
|    if (-not $global:AzDceDetails) { . $rebuild }
|    $dce = . $findHere
|    $dcr = . $findRule
|    if (-not $dce -or ($dcrRg -and -not $dcr)) { . $rebuild; $dce = . $findHere; $dcr = . $findRule }
|    if (-not $dce) {
|        $same = @($global:AzDceDetails | Where-Object { $_ -and $_.name -eq $global:SI_DceName })
|        if ($same.Count -ne 1) {
|            throw ("Data collection endpoint '{0}' was not found in resource group '{1}' of subscription '{2}'. {3} endpoint(s) of that name exist elsewhere, so nothing was posted -- set SI_DceResourceGroup to the one this install uses." -f $global:SI_DceName, $dceRg, $sub, $same.Count)
|        }
|        $dce = $same[0]
|    }
|    $bound = if ($dcr -and $dcr.properties) { [string]$dcr.properties.dataCollectionEndpointId } else { '' }
|    if ($bound -and $bound -ne [string]$dce.id) {
|        $b = @($global:AzDceDetails | Where-Object { $_ -and [string]$_.id -eq $bound }) | Select-Object -First 1
|        if (-not $b) { . $rebuild; $b = @($global:AzDceDetails | Where-Object { $_ -and [string]$_.id -eq $bound }) | Select-Object -First 1 }
|        if ($b -and $b.name -eq $global:SI_DceName) {
|            Write-Verbose ("Data collection rule '{0}' is bound to {1}; posting through it." -f $DcrName, $bound)
|            $dce = $b
|        }
|    }
|    $global:AzDceDetails = @($dce)
|    if ($dcr) { $global:AzDcrDetails = @($dcr) }
|    elseif ($global:AzDcrDetails) { $global:AzDcrDetails = @($global:AzDcrDetails | Where-Object { $_ -and $_.name -ne $DcrName }) }
|}
|function Resolve-SICorrelationAuthParams {
|    <#
|        MI > SPN+cert > SPN+secret, resolved into the splat AzLogDcrIngestPS wants.
|        Mirrors Send-SIRunHealthRow deliberately -- see this file's header for why it is not shared.
|    #>
|    $spnAppId     = if ($global:SI_SPN_AppId)    { $global:SI_SPN_AppId }    else { $global:SI_LogIngest_AppId }
|    $spnSecret    = if ($global:SI_SPN_Secret)   { $global:SI_SPN_Secret }   else { $global:SI_LogIngest_Secret }
|    $spnTenantId  = if ($global:SI_SPN_TenantId) { $global:SI_SPN_TenantId } else { $global:SI_LogIngest_TenantId }
|    $spnCertThumb = [string]$global:SI_SPN_CertThumbprint
|
|    # Auto-detect which store actually holds the private key. A thumbprint in the wrong store reads as
|    # "no cert" and falls through to the secret branch, which then fails on a tenant that has no secret.
|    $spnCertStore = if ($global:SI_SPN_CertStoreLocation) { [string]$global:SI_SPN_CertStoreLocation }
|                    elseif ($spnCertThumb) {
|                        $clean = $spnCertThumb -replace '\s',''
|                        if (Get-PSDrive -Name Cert -ErrorAction SilentlyContinue) {
|                            $resolved = 'LocalMachine'
|                            foreach ($s in 'LocalMachine','CurrentUser') {
|                                $c = Get-ChildItem "Cert:\$s\My" -ErrorAction SilentlyContinue |
|                                     Where-Object { $_.Thumbprint -eq $clean -and $_.HasPrivateKey } |
|                                     Select-Object -First 1
|                                if ($c) { $resolved = $s; break }
|                            }
|                            $resolved
|                        } else {
|                            # #209: no Cert: drive (a Linux container) -- read the X509Store instead.
|                            if (-not (Get-Command Get-SICertStoreLocation -ErrorAction Ignore)) {
|                                . (Join-Path (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)) 'auth/Find-SICertificate.ps1')
|                            }
|                            Get-SICertStoreLocation -Thumbprint $clean
|                        }
|                    } else { 'LocalMachine' }
|
|    $useMi   = $global:SI_PreferUami -and -not [string]::IsNullOrWhiteSpace($global:SI_UAMI_ClientId)
|    $useCert = -not $useMi -and -not [string]::IsNullOrWhiteSpace($spnCertThumb)
|
|    if ($useMi) {
|        return @{ UseManagedIdentity = $true; ManagedIdentityClientId = $global:SI_UAMI_ClientId }
|    }
|    if ($useCert) {
|        return @{
|            AzAppId                       = $spnAppId
|            AzAppCertificateThumbprint    = $spnCertThumb
|            AzAppCertificateStoreLocation = $spnCertStore
|            TenantId                      = $spnTenantId
|        }
|    }
|    @{ AzAppId = $spnAppId; AzAppSecret = $spnSecret; TenantId = $spnTenantId }
|}
|
|function Send-SIObjectMapRows {
|    <#
|        Publish the map to SI_ObjectMap_CL through the normal DCR path.
|
|        SQL COMPUTES AND HOLDS, LA PUBLISHES -- and there is no SQL yet, so today this IS the store.
|
|        🔴 CORRECTED 2026-08-13. This header used to say the deterministic seed means "an object's id is
|        recomputed identically every run", and that key-stability memory was "an OPTIMISATION over a
|        correctness property the core already has". THAT WAS WRONG, and believing it is what would ship
|        duplicate CIs. The property the core has is `same INPUT -> same id`. The property a connector
|        needs is `same OBJECT -> same id`. They diverge whenever group membership changes:
|
|          * Measured: adding one member carrying a lower-sorting exposure-graph id moved a group from
|            `exposuregraphnodeid:aaa` to `exposuregraphnodeid:000`. The seed is the ordinally-lowest
|            value of the highest-priority type PRESENT IN THE GROUP, so any arrival or departure moves
|            it.
|          * Departures are routine: the same day, EndpointEG returned 0 rows on a timeout and 51 assets
|            left the snapshot.
|          * Anchors churn independently -- MDE ids rotate, a rebuilt VM gets a new ARM path, a
|            re-enrolled device gets a new AadDeviceId.
|
|        So SQL key-stability is a CORRECTNESS PREREQUISITE before the connector may create CIs, not an
|        optimisation. Publishing to LA without it is fine -- reading a map is harmless. CREATING a
|        ServiceNow CI from an id that can move is not.
|
|        Decided 2026-08-13 (V3-ARCHITECTURE 2.3a): a minted UUIDv5-from-birth-anchor id, stored, with an
|        anchor ledger and a superseded table. Until that exists, ids emitted here are PROVISIONAL and a
|        connector must not create CIs from them.
|
|        NOT best-effort. Unlike the run-health heartbeat, this IS the output -- a swallowed failure
|        would leave consumers reading a stale map while every run reported success.
|    #>
|    param(
|        [Parameter(Mandatory)][AllowEmptyCollection()][object[]]$Rows,
|        [string]$TableName = 'SI_ObjectMap',
|        [string]$DcrName
|    )
|
|    if (@($Rows).Count -eq 0) {
|        Write-Warning 'correlation: nothing to publish -- 0 map rows. Not posting.'
|        return 0
|    }
|    if ([string]::IsNullOrWhiteSpace($DcrName)) {
|        $DcrName = if (-not [string]::IsNullOrWhiteSpace([string]$global:SI_ObjectMap_DcrName)) {
|            [string]$global:SI_ObjectMap_DcrName
|        } else { 'dcr-si-objectmap' }
|    }
|
|    $savedVerbose = $global:VerbosePreference
|    $global:VerbosePreference = 'SilentlyContinue'
|    $lock = $null
|    try {
|        $authParams = Resolve-SICorrelationAuthParams
|        Initialize-SIIngestGlobals
|        $spnObjectId = if ($global:SI_SPN_ObjectId) { $global:SI_SPN_ObjectId } else { $global:SI_LogIngest_ObjectId }
|
|        # #475 -- A TABLE + RULE ALREADY MADE READY IN THIS PROCESS FOR THESE COLUMNS IS NOT CHECKED AGAIN. The steps below
|        # (endpoint + rule selection twice, the table / rule update with its coverage check, the cache refresh) are several
|        # Azure calls; they ran for every batch, and a run collected in parts posts its records in dozens of batches
|        # (customer H 2026-10-09: 96,551 records). A batch whose columns were all made ready earlier in this process posts
|        # through the same pinned endpoint and rule; a batch with a NEW column takes the full path again.
|        $readyKey = ('{0}|{1}' -f $TableName, $DcrName).ToLowerInvariant()
|        $batchCols = Get-SIObjectMapColumns -Rows @($Rows)
|        # in the run cache (global, like the tokens: this file is dot-sourced at different depths, so $script: differs)
|        $rcache = Get-SILogIngestRunCache
|        if (-not ($rcache.ObjectMapReady -is [hashtable])) { $rcache.ObjectMapReady = @{} }
|        $ready = $rcache.ObjectMapReady[$readyKey]
|        if ($ready -and (Test-SIObjectMapColumnsReady -Ready $ready.Columns -Columns $batchCols)) {
|            $global:AzDceDetails = @($ready.Dce); $global:AzDcrDetails = @($ready.Dcr)
|            $data = @($Rows)
|            $data = Repair-SILogColumnName -Data $data 4>$null
|            $data = Format-SILogRowsToSchema -Data $data 4>$null
|            $null = Send-SILogData -DceName $global:SI_DceName -DcrName $DcrName -Data $data -TableName $TableName @authParams 4>$null
|            return @($data).Count
|        }
|        # several processes of one run publish at once (the records of a run collected in parts): the table / rule update
|        # is done by one at a time (SI_INGEST_LOCK_FILE), so two never update the same rule over each other
|        $lock = Enter-SIIngestLock
|
|        # 🔴 THE WHOLE SET, NOT ONE ROW -- CORRECTED 2026-08-31. `-Data` was
|        # `@($Rows | Select-Object -First 1)`. AzLogDcrIngestPS INFERS the table + DCR column set
|        # from what it is handed, so one row defined the schema for the entire table: a row lacking
|        # an optional field meant that column was never created, and every other row's value for it
|        # was DROPPED AT INGEST, silently, for the life of the table.
|        # 🪤 Nothing errors. The engine reports rows posted, the table exists, and the field is
|        # simply absent -- indistinguishable from "no object had a value".
|        # 📌 The four profilers already got this right (Invoke-Output.ps1's `$schemaSample` is the
|        # FULL dataset, commented "full dataset for type inference"). Only the engines that publish
|        # their own v3 tables carried the shortcut.
|        #
|        # 🔴 AND THIS COMMENT MUST STAY *ABOVE* THE CALL, NOT INSIDE IT (audit #102, 2026-09-02).
|        # It was written between two backtick-continued argument lines, and **a comment TERMINATES a
|        # backtick continuation**: everything after it was dropped, including the `-Data @($Rows)` this
|        # very comment was added to introduce. Correlation then failed at publish on every run --
|        # `missing mandatory parameters: Data AzDcrSetLogIngestApiAppPermissionsDcrLevel
|        # AzLogDcrTableCreateFromReferenceMachine`, which is exactly the arguments that follow it here.
|        # #199 -- pin BEFORE the create/update, not only before the post.
|        Select-SIIngestTarget -AuthParams $authParams -DcrName $DcrName
|        $null = Update-SILogTableSchema `
|            -AzLogWorkspaceResourceId                   $global:SI_WorkspaceResourceId `
|            @authParams `
|            -DceName                                    $global:SI_DceName `
|            -DcrName                                    $DcrName `
|            -DcrResourceGroup                           $global:SI_DcrResourceGroup `
|            -TableName                                  $TableName `
|            -Data                                       @($Rows) `
|            -LogIngestServicePricipleObjectId           $spnObjectId `
|            -AzDcrSetLogIngestApiAppPermissionsDcrLevel $false `
|            -AzLogDcrTableCreateFromAnyMachine          $true `
|            -AzLogDcrTableCreateFromReferenceMachine    @() 4>$null
|
|        # Re-sync the DCE/DCR cache so a freshly created DCR's immutableId is known before the
|        # name-only lookup inside Post-*. Without it the module falls back to the DCE's location
|        # field as a bogus immutableId and the ingestion API answers 404 'westeurope'.
|        try {
|            $ensureFn = Get-Command -Name 'Ensure-SecurityInsightAzDceDcrCache' -ErrorAction Ignore
|            if ($ensureFn) {
|                & $ensureFn @authParams `
|                    -SubscriptionId   $global:SI_AzSubscriptionId `
|                    -DceResourceGroup $global:SI_DceResourceGroup `
|                    -DcrResourceGroup $global:SI_DcrResourceGroup `
|                    -Force 4>$null
|            }
|        } catch { }
|
|        # 📌 SUPERSEDED 2026-10-01 (#199): Select-SIIngestTarget above now builds and pins the caches BEFORE the
|        # create/update -- the module resolves the endpoint by name inside CheckCreateUpdate too, so pinning only
|        # here was too late. The history below is kept for the BlockCopy lesson.
|        # 🪤 DO NOT PRE-POPULATE THE CACHES HERE. Tried on 2026-08-30, mirroring the profiler's
|        # `$global:AzDceDetails = Get-AzDceListAll @authParams`, on the reasoning that filtering a
|        # cache that does not exist yet would be a silent no-op. It is not a no-op -- by this point
|        # `CheckCreateUpdate-TableDcr-Structure` (called above) has already built both caches, which
|        # is why the DCR pin below has always worked. The rebuild is redundant work, nothing more.
|        # 📌 It was briefly believed to have CAUSED the "BlockCopy ... Object must be an array of
|        # primitives" error that appeared once the 403 was gone. It did not, and the wrong version of
|        # this note lived here for an hour. That error was a real defect in AzLogDcrIngestPS 1.7.1 --
|        # `return $bytes` enumerates the array, so the caller binds object[] and [Buffer]::BlockCopy
|        # rejects it -- which broke the UNCOMPRESSED path for every caller of the module. Fixed
|        # upstream in 1.7.2 (SI finding #81). Removing these lines did not make it go away; only the
|        # module fix did.
|
|        # DCR name-collision guard. One SPN can see same-named DCRs in several subscriptions -- there
|        # are already three DCEs called dce-securityinsight in this tenant -- and the module's name-only
|        # lookup then picks one at random. Pin to (sub + RG + name) before posting.
|        if ($global:AzDcrDetails -and $global:SI_AzSubscriptionId -and $global:SI_DcrResourceGroup) {
|            $picked = @($global:AzDcrDetails | Where-Object {
|                $_.name -eq $DcrName -and
|                $_.id   -like "*/subscriptions/$($global:SI_AzSubscriptionId)/resourceGroups/$($global:SI_DcrResourceGroup)/*"
|            }) | Select-Object -First 1
|            if ($picked) { $global:AzDcrDetails = @($picked) }
|        }
|
|        # 🔴 AND THE SAME GUARD FOR THE **DCE** -- its absence is why this engine could never publish.
|        # The comment above names the hazard exactly ("three DCEs called dce-securityinsight") and then
|        # pins only the DCR. `Post-*` resolves the DCE by NAME-ONLY against $global:AzDceDetails, so it
|        # could pick an endpoint in a DIFFERENT subscription and post this workspace's DCR immutableId
|        # to it -- which the Log Ingestion API answers with **HTTP 403**.
|        # MEASURED 2026-08-30: three DCEs named `dce-securityinsight` exist across this tenant (one in
|        # the workspace's own subscription, two in a sibling), and every correlation run ended
|        # `[ERROR] Engine failed: Log Ingestion API request failed. HTTP Status: 403` AFTER doing all
|        # of its real work -- 1296 rows read, 1291 objects correlated, ledger updated, 2228 map rows
|        # built -- and losing the lot at the final POST. That is why the handoff records correlation as
|        # "built + run on real data, never published": it was never a correlation defect at all.
|        # 🔑 THE PROFILER ALREADY SOLVES THIS. `Apply-SIDcrScopeFilter` (asset-profiling/stages/
|        # Invoke-Output.ps1) filters BOTH caches to the configured sub + RG, which is exactly why the
|        # four profilers ingest happily while this engine 403s on the same credentials. Operator,
|        # 2026-08-30: *"it must use same auth as the design is using to send data to la in the
|        # profiler"* -- so this mirrors that filter rather than inventing a third variant.
|        # 📌 Same auth params, same scope pin. The DCE RG falls back to the DCR RG, matching the
|        # profiler's own default of 'rg-securityinsight' when SI_DceResourceGroup is unset.
|        $_dceRg = if ($global:SI_DceResourceGroup) { [string]$global:SI_DceResourceGroup }
|                  else { [string]$global:SI_DcrResourceGroup }
|        if ($global:AzDceDetails -and $global:SI_AzSubscriptionId -and $_dceRg) {
|            $_pickedDce = @($global:AzDceDetails | Where-Object {
|                $_.id -like "*/subscriptions/$($global:SI_AzSubscriptionId)/resourceGroups/$_dceRg/*"
|            })
|            if ($_pickedDce.Count -gt 0) { $global:AzDceDetails = @($_pickedDce) }
|        }
|
|        # #199 -- again before the post: the cache refresh above narrowed it to this install's endpoint, which is
|        # not the rule's own when the rule is bound elsewhere.
|        Select-SIIngestTarget -AuthParams $authParams -DcrName $DcrName
|        # ready for these columns in this process (#475): the next batch with no new column posts straight away
|        $known = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|        if ($ready) { foreach ($c in $ready.Columns) { [void]$known.Add($c) } }
|        foreach ($c in $batchCols) { [void]$known.Add($c) }
|        $rcache.ObjectMapReady[$readyKey] = [pscustomobject]@{ Columns = $known; Dce = @($global:AzDceDetails); Dcr = @($global:AzDcrDetails) }
|        Exit-SIIngestLock -Lock $lock; $lock = $null
|        $data = @($Rows)
|        $data = Repair-SILogColumnName -Data $data 4>$null
|        $data = Format-SILogRowsToSchema -Data $data 4>$null
|        $null = Send-SILogData `
|            -DceName   $global:SI_DceName `
|            -DcrName   $DcrName `
|            -Data      $data `
|            -TableName $TableName `
|            @authParams 4>$null
|
|        @($data).Count
|    }
|    finally {
|        if ($lock) { Exit-SIIngestLock -Lock $lock }
|        if ($null -ne $savedVerbose) { $global:VerbosePreference = $savedVerbose }
|    }
|}
|
|function Get-SIObjectMapColumns {
|    <# PURE. Every column name of a batch of rows (PSObject properties or dictionary keys), once. #>
|    param([AllowEmptyCollection()][object[]]$Rows = @())
|    $set = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    foreach ($r in $Rows) {
|        if ($null -eq $r) { continue }
|        if ($r -is [System.Collections.IDictionary]) { foreach ($k in $r.Keys) { [void]$set.Add([string]$k) } }
|        else { foreach ($p in $r.PSObject.Properties) { [void]$set.Add($p.Name) } }
|    }
|    $out = New-Object System.Collections.Generic.List[string]
|    foreach ($c in $set) { $out.Add($c) }
|    , $out.ToArray()
|}
|
|function Test-SIObjectMapColumnsReady {
|    <# PURE. $true when every column of the batch is among the columns already made ready. #>
|    param($Ready, [AllowEmptyCollection()][string[]]$Columns = @())
|    if ($null -eq $Ready) { return $false }
|    foreach ($c in $Columns) { if (-not $Ready.Contains($c)) { return $false } }
|    $true
|}
|
|function Enter-SIIngestLock {
|    <#
|        The cross-process lock of the table / rule update (SI_INGEST_LOCK_FILE, set by a parent that runs several publishing
|        processes at once). No variable = no lock ($null). Waits up to 20 minutes; then goes on without it, said once -- a
|        lock that cannot be taken never stops a publish (the coverage check before every post still guards the rule).
|    #>
|    param([int]$WaitSeconds = 1200)
|    $path = [string][Environment]::GetEnvironmentVariable('SI_INGEST_LOCK_FILE')
|    if ([string]::IsNullOrWhiteSpace($path)) { return $null }
|    $until = [datetime]::UtcNow.AddSeconds($WaitSeconds)
|    while ([datetime]::UtcNow -lt $until) {
|        try { return [System.IO.File]::Open($path, [System.IO.FileMode]::OpenOrCreate, [System.IO.FileAccess]::ReadWrite, [System.IO.FileShare]::None) }
|        catch { Start-Sleep -Milliseconds 500 }
|    }
|    Write-Warning ('the table update lock ({0}) was not free for {1} seconds -- this process goes on without it' -f $path, $WaitSeconds)
|    $null
|}
|
|function Exit-SIIngestLock {
|    param($Lock)
|    if ($Lock) { try { $Lock.Dispose() } catch { } }
|}
|
|# =====================================================================================================================
|#  LOG INGESTION OVER PLAIN REST -- SecurityInsight needs no PowerShell module (no AzLogDcrIngestPS, no Az.*).
|# =====================================================================================================================
|<#
|    Every SI call site calls the SI wrapper of the job; each wrapper does it over plain REST (its *Rest function):
|
|        SI wrapper                  replaces (AzLogDcrIngestPS)                            SI REST function
|        Get-SIDceList               Get-AzDceListAll                                       Get-SIDceListRest
|        Get-SIDcrList               Get-AzDcrListAll                                       Get-SIDcrListRest
|        Update-SILogTableSchema     CheckCreateUpdate-TableDcr-Structure                   Update-SILogTableSchemaRest
|        Send-SILogData              Post-AzLogAnalyticsLogIngestCustomLogDcrDce-Output     Send-SILogDataRest
|        Add-SICollectionTime        Add-CollectionTimeToAllEntriesInArray                  Add-SICollectionTimeRest
|        Add-SIColumnData            Add-ColumnDataToAllEntriesInArray                      Add-SIColumnDataRest
|        Repair-SILogColumnName      ValidateFix-AzLogAnalyticsTableSchemaColumnNames       Repair-SILogColumnNameRest
|        Format-SILogRowsToSchema    Build-DataArrayToAlignWithSchema                       Format-SILogRowsToSchemaRest
|        Get-SILogSchemaArray        Get-ObjectSchemaAsArray                                Get-SILogSchemaRest -As Array
|        Get-SILogSchemaHash         Get-ObjectSchemaAsHash                                 Get-SILogSchemaRest -As Hash
|        Test-SILogTableDcrStatus    Get-AzLogAnalyticsTableAzDataCollectionRuleStatus      Test-SILogTableDcrStatusRest
|        Set-SILogTable              CreateUpdate-AzLogAnalyticsCustomLogTableDcr           Set-SILogTableRest
|        Set-SILogDcr                CreateUpdate-AzDataCollectionRuleLogIngestCustomLog    Set-SILogDcrRest
|
|    The wrappers keep the parameter names and types the call sites were written against, so no call site changed.
|
|    PS 5.1 safe: no ?. / ??, no RSA.ImportFromPem. Works on pwsh 7 / Linux (no Cert: drive needed). Community + Pro:
|    this file never references a Pro path.
|#>
|
|function Get-SILogIngestWrapperMap {
|    <# The wrapper -> replaced function -> REST function table above, as data (the wiring tests read it). #>
|    [ordered]@{
|        'Get-SIDceList'            = @{ Replaces = 'Get-AzDceListAll';                                   Rest = 'Get-SIDceListRest' }
|        'Get-SIDcrList'            = @{ Replaces = 'Get-AzDcrListAll';                                   Rest = 'Get-SIDcrListRest' }
|        'Update-SILogTableSchema'  = @{ Replaces = 'CheckCreateUpdate-TableDcr-Structure';               Rest = 'Update-SILogTableSchemaRest' }
|        'Send-SILogData'           = @{ Replaces = 'Post-AzLogAnalyticsLogIngestCustomLogDcrDce-Output'; Rest = 'Send-SILogDataRest' }
|        'Add-SICollectionTime'     = @{ Replaces = 'Add-CollectionTimeToAllEntriesInArray';              Rest = 'Add-SICollectionTimeRest' }
|        'Add-SIColumnData'         = @{ Replaces = 'Add-ColumnDataToAllEntriesInArray';                  Rest = 'Add-SIColumnDataRest' }
|        'Repair-SILogColumnName'   = @{ Replaces = 'ValidateFix-AzLogAnalyticsTableSchemaColumnNames';   Rest = 'Repair-SILogColumnNameRest' }
|        'Format-SILogRowsToSchema' = @{ Replaces = 'Build-DataArrayToAlignWithSchema';                   Rest = 'Format-SILogRowsToSchemaRest' }
|        'Get-SILogSchemaArray'     = @{ Replaces = 'Get-ObjectSchemaAsArray';                            Rest = 'Get-SILogSchemaRest' }
|        'Get-SILogSchemaHash'      = @{ Replaces = 'Get-ObjectSchemaAsHash';                             Rest = 'Get-SILogSchemaRest' }
|        'Test-SILogTableDcrStatus' = @{ Replaces = 'Get-AzLogAnalyticsTableAzDataCollectionRuleStatus';  Rest = 'Test-SILogTableDcrStatusRest' }
|        'Set-SILogTable'           = @{ Replaces = 'CreateUpdate-AzLogAnalyticsCustomLogTableDcr';       Rest = 'Set-SILogTableRest' }
|        'Set-SILogDcr'             = @{ Replaces = 'CreateUpdate-AzDataCollectionRuleLogIngestCustomLog'; Rest = 'Set-SILogDcrRest' }
|    }
|}
|
|# ---- the wrappers ------------------------------------------------------------------------------------------------
|# Each declares the parameters the call sites pass (names + types) and forwards @PSBoundParameters: only what the call
|# site bound, with the value it bound, including -Verbose:$false. NOT `@args`: measured 2026-10-03 on PS 5.1 and 7.6,
|# `@args` splits `-Name:$value` into a bare switch plus a positional value.
|
|function Get-SIDceList {
|    [CmdletBinding()]
|    param([string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    return (Get-SIDceListRest @PSBoundParameters)
|}
|
|function Get-SIDcrList {
|    [CmdletBinding()]
|    param([string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    return (Get-SIDcrListRest @PSBoundParameters)
|}
|
|function Get-SIDcrCreateRefusal {
|    <# PURE. The line of a DCR / table create's captured output in which Azure (or the create itself) REFUSED it -- the
|       Microsoft answer to surface, '' when there is none. A refused create never makes the rule appear, so it is not waited for.
|       'skipping create' / 'already exists in' (a rule of that name in ANOTHER resource group) is a refusal too: the create did nothing. #>
|    param([AllowNull()][AllowEmptyString()][string]$CreateOutput)
|    if ([string]::IsNullOrWhiteSpace($CreateOutput)) { return '' }
|    $re = '(?i)AuthorizationFailed|LinkedAuthorizationFailed|\(Forbidden\)|\b403\b|\(Unauthorized\)|\b401\b|InvalidPayload|InvalidTemplate|InvalidRequestContent|BadRequest|ResourceGroupNotFound|SubscriptionNotFound|WorkspaceNotFound|Step 3 threw|skipping create|already exists in'
|    foreach ($l in ($CreateOutput -split '\r?\n')) { if ($l -match $re) { return $l.Trim() } }
|    ''
|}
|
|function Wait-SIDcrReady {
|    <#
|        Fix request 2a40d950 (owner 2026-10-22: no fixed limits on SI's own work): after the table / rule create, WAIT UNTIL
|        THE RULE IS READY and read it back -- never a fixed number of seconds that gives up while Azure is still making it
|        (it was 240 s). A not-found / no-immutableId answer right after a create means "not yet" (REQUIREMENTS #619). It stops
|        only on EVIDENCE that waiting cannot help, and says Microsoft's answer:
|          * the create's own output carries a refusal (Get-SIDcrCreateRefusal) -- before any wait;
|          * Azure says the rule's provisioning FAILED;
|          * reading the rule is refused (401 / 403 -- the identity may not read it);
|          * the create has RETURNED and two read-backs in a row, spaced by the progress pace (-MaxPauseSeconds), find NO rule
|            at all: the create did nothing, so waiting cannot help (review S1: it polled until the job died). A rule that IS
|            there but still provisioning is waited for without a deadline.
|        Any other failed read is a transient answer: said, and read again. Progress is said on every read (elapsed, what was
|        seen); the first read is at once (a rule that is already there costs no wait); the pause between reads grows from -FirstPauseSeconds to -MaxPauseSeconds (a pace, never a deadline).
|        -Probe { } -> @{ ImmutableId; State } of the rule as SI's own lists see it now ($null = not there yet); it throws
|        when the read fails. -Sleep { param($s) } / -Log { param($m) } are seams. Returns @{ Ready; ImmutableId; Waited; Why }.
|    #>
|    param([Parameter(Mandatory)][string]$DcrName, [Parameter(Mandatory)][scriptblock]$Probe, [AllowNull()][AllowEmptyString()][string]$CreateOutput,
|          [scriptblock]$Sleep = { param($s) Start-Sleep -Seconds $s }, [scriptblock]$Log = { param($m) Write-Host $m },
|          [int]$FirstPauseSeconds = 15, [int]$MaxPauseSeconds = 60, [AllowEmptyString()][string]$Location = '')
|    $refused = Get-SIDcrCreateRefusal -CreateOutput $CreateOutput
|    if ($refused) {
|        # read back ONCE: a refusal of a later part (the table, a role) can come after the rule itself was made -- then it is used
|        $r = $null; try { $r = & $Probe } catch { $r = $null }
|        if ($null -ne $r -and [string]$r.ImmutableId -and [string]$r.ImmutableId -notlike '*location*' -and [string]$r.ImmutableId -ne $Location -and [string]$r.State -notmatch '(?i)^failed$') {
|            & $Log ("DCR '{0}' is ready although the create reported: {1}" -f $DcrName, $refused)
|            return @{ Ready = $true; ImmutableId = [string]$r.ImmutableId; Waited = 0; Why = '' }
|        }
|        return @{ Ready = $false; ImmutableId = ''; Waited = 0; Why = ("the create of DCR '{0}' was refused -- {1}" -f $DcrName, $refused) }
|    }
|    $waited = 0; $pause = [Math]::Max(1, $FirstPauseSeconds); $absent = 0
|    while ($true) {
|        $seen = 'not there yet'
|        try {
|            $r = & $Probe
|            if ($null -ne $r) {
|                $imm = [string]$r.ImmutableId; $st = [string]$r.State
|                if ($st -match '(?i)^failed$') { return @{ Ready = $false; ImmutableId = ''; Waited = $waited; Why = ("Azure reports DCR '{0}' with provisioning state Failed" -f $DcrName) } }
|                if ($imm -and $imm -notlike '*location*' -and $imm -ne $Location) { & $Log ("DCR immutableId resolved after {0}s: {1}" -f $waited, $imm); return @{ Ready = $true; ImmutableId = $imm; Waited = $waited; Why = '' } }
|                $seen = $(if ($st) { "there, provisioning state $st, no immutableId yet" } else { 'there, no immutableId yet' })
|                $absent = 0
|            } else {
|                $absent++
|                if ($absent -ge 2) {
|                    $said = @(([string]$CreateOutput) -split '\r?\n' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
|                    $answer = $(if ($said.Count) { $said[-1] } else { 'nothing (the create returned no output)' })
|                    return @{ Ready = $false; ImmutableId = ''; Waited = $waited; Why = ("the rule was not created; Azure answered: {0} -- DCR '{1}' was not found on two read-backs {2}s apart after the create returned" -f $answer, $DcrName, [Math]::Max(1, $MaxPauseSeconds)) }
|                }
|            }
|        } catch {
|            $m = ("$($_.Exception.Message)" -replace '\s+', ' ').Trim()
|            if ($m -match '(?i)\b401\b|\b403\b|AuthorizationFailed|Forbidden|Unauthorized') { return @{ Ready = $false; ImmutableId = ''; Waited = $waited; Why = ("reading DCR '{0}' was refused -- {1}" -f $DcrName, $m) } }
|            $seen = "the read failed ($m) -- read again"
|        }
|        & $Log ("waiting for DCR '{0}' to be ready ({1}s so far; {2}) ..." -f $DcrName, $waited, $seen)
|        # after a read that found no rule at all, the next read is a full progress pace later (the second read-back of the stop rule)
|        $nap = $(if ($absent -ge 1) { [Math]::Max($pause, [Math]::Max(1, $MaxPauseSeconds)) } else { $pause })
|        & $Sleep $nap
|        $waited += $nap
|        $pause = [Math]::Min([Math]::Max(1, $MaxPauseSeconds), $pause * 2)
|    }
|}
|
|function Update-SILogTableSchema {
|    [CmdletBinding()]
|    param([Array]$Data, [string]$AzLogWorkspaceResourceId, [string]$TableName, [string]$DcrName, [string]$DcrResourceGroup, [string]$DceName,
|          [AllowEmptyCollection()][string]$LogIngestServicePricipleObjectId, [boolean]$AzDcrSetLogIngestApiAppPermissionsDcrLevel,
|          [boolean]$AzLogDcrTableCreateFromAnyMachine, [string]$SchemaMode, [boolean]$EnableUploadViaLogHub,
|          [AllowEmptyCollection()][array]$AzLogDcrTableCreateFromReferenceMachine,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    # A rule that already feeds ANOTHER table is never repurposed, and columns this call adds to an existing rule are
|    # noted so the post can check that they are stored (Start-SILogDcrWatch / Complete-SILogDcrWatch, below).
|    $watch = Start-SILogDcrWatch -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -TableName $TableName -WorkspaceResourceId $AzLogWorkspaceResourceId -Bound $PSBoundParameters
|    # A NEW rule for a table that already exists is declared from the TABLE (its columns, with their types):
|    # Set-SILogDcrRest does this itself.
|    $out = Update-SILogTableSchemaRest @PSBoundParameters
|    # The rule this install posts through must declare EVERY column of the data -- a column it does not declare is
|    # dropped by Azure without an error. Missing ones are added from the table; any still missing refuses the post.
|    # Before Complete-SILogDcrWatch, so columns added here are checked after the post like any other new column.
|    $null = Assert-SILogDcrCoversData -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -TableName $TableName -WorkspaceResourceId $AzLogWorkspaceResourceId -DceName $DceName -Data $Data -Bound $PSBoundParameters
|    Complete-SILogDcrWatch -Watch $watch
|    $out
|}
|
|function Send-SILogData {
|    [CmdletBinding()]
|    param([array]$Data, [AllowEmptyString()][string]$DcrName, [AllowEmptyString()][string]$DceName, [string]$TableName,
|          [string]$BatchAmount, [bool]$EnableUploadViaLogHub, [string]$LogHubPath,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation, [string]$TenantId,
|          [Nullable[bool]]$EnableCompression, [Nullable[bool]]$UseManagedIdentity, [string]$ManagedIdentityClientId)
|    $out = Send-SILogDataRest @PSBoundParameters
|    # Columns added to this rule earlier in the run: check that Log Analytics really stores their values.
|    Confirm-SILogNewColumns -DcrName $DcrName -TableName $TableName -Data $Data -Bound $PSBoundParameters
|    $out
|}
|
|function Add-SICollectionTime {
|    [CmdletBinding()]
|    param([Array]$Data)
|    return (Add-SICollectionTimeRest @PSBoundParameters)
|}
|
|function Add-SIColumnData {
|    [CmdletBinding()]
|    param([Array]$Data, [string]$Column1Name, [string]$Column1Data, [string]$Column2Name, [string]$Column2Data, [string]$Column3Name, [string]$Column3Data)
|    return (Add-SIColumnDataRest @PSBoundParameters)
|}
|
|function Repair-SILogColumnName {
|    [CmdletBinding()]
|    param([Array]$Data)
|    return (Repair-SILogColumnNameRest @PSBoundParameters)
|}
|
|function Format-SILogRowsToSchema {
|    [CmdletBinding()]
|    param([Array]$Data)
|    return (Format-SILogRowsToSchemaRest @PSBoundParameters)
|}
|
|function Get-SILogSchemaArray {
|    [CmdletBinding()]
|    param([Array]$Data, [string[]]$ReturnType)
|    return (Get-SILogSchemaRest -As Array @PSBoundParameters)
|}
|
|function Get-SILogSchemaHash {
|    [CmdletBinding()]
|    param([Array]$Data, [string[]]$ReturnType)
|    return (Get-SILogSchemaRest -As Hash @PSBoundParameters)
|}
|
|function Test-SILogTableDcrStatus {
|    [CmdletBinding()]
|    param([string]$AzLogWorkspaceResourceId, [string]$TableName, [string]$DcrName, [array]$SchemaSourceObject,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    return (Test-SILogTableDcrStatusRest @PSBoundParameters)
|}
|
|function Set-SILogTable {
|    [CmdletBinding()]
|    param([string]$TableName, [array]$SchemaSourceObject, [string]$AzLogWorkspaceResourceId, [string]$SchemaMode,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    return (Set-SILogTableRest @PSBoundParameters)
|}
|
|function Set-SILogDcr {
|    [CmdletBinding()]
|    param([array]$SchemaSourceObject, [string]$AzLogWorkspaceResourceId, [string]$DceName, [string]$DcrResourceGroup, [string]$DcrName, [string]$TableName,
|          [boolean]$AzDcrSetLogIngestApiAppPermissionsDcrLevel, [AllowEmptyCollection()][string]$LogIngestServicePricipleObjectId, [string]$SchemaMode,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation,
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    $watch = Start-SILogDcrWatch -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -TableName $TableName -WorkspaceResourceId $AzLogWorkspaceResourceId -Bound $PSBoundParameters
|    $out = Set-SILogDcrRest @PSBoundParameters
|    Complete-SILogDcrWatch -Watch $watch
|    $out
|}
|
|# =====================================================================================================================
|#  A RULE IS NEVER REPURPOSED, AND NEW COLUMNS ARE CHECKED -- both engines (these run around the wrappers above)
|#
|#  1. A data collection rule that already feeds ANOTHER table is never changed to feed this one. Measured in the 2.2 ->
|#     3.0 upgrade test: a setup-written 2.2 config named its public-IP rule 'dcr-si-publicip-profile' (feeding the 2.2
|#     public-IP table); 3.0's own default uses the same name for its new table, and the module REWROTE the rule -- the
|#     old flow was gone and the first post failed. Start-SILogDcrWatch refuses before anything is written.
|#  2. Columns added to an EXISTING rule land empty for a while: Azure accepts the post, but drops the new columns'
|#     values until the change has reached the ingestion pipeline (measured: the first 3.0 run after the upgrade wrote
|#     SI_AssetName / SI_AssetId empty on 134 of 134 rows; empty again 4 and 18 minutes after a column was added; filled
|#     hours later). The rule shows the new column at once, so the rule itself is no signal. Complete-SILogDcrWatch
|#     notes what was added; Confirm-SILogNewColumns, after the post, asks Log Analytics whether this run's values were
|#     STORED, and when they were not, the run says so and records it (Get-SILogIngestNotes -> the run's outcome is
|#     success-partial, so nothing downstream reads the snapshot as whole).
|#  Every read here is best effort: a rule that cannot be read is never a reason to stop a publish -- only a rule that IS
|#  read and feeds another table is.
|# =====================================================================================================================
|
|function Get-SILogDcrStreams {
|    <# PURE. The streams an existing rule writes: each data flow's outputStream, else the flow's streams; a rule with
|       no data flows -> its declared streams. #>
|    param([AllowNull()]$Dcr)
|    $out = New-Object System.Collections.Generic.List[string]
|    if ($null -eq $Dcr -or $null -eq $Dcr.properties) { return @() }
|    foreach ($f in @($Dcr.properties.dataFlows)) {
|        if ($null -eq $f) { continue }
|        $names = if ($f.PSObject.Properties['outputStream'] -and $f.outputStream) { @([string]$f.outputStream) } else { @(@($f.streams) | ForEach-Object { [string]$_ }) }
|        foreach ($n in $names) { if ($n -and -not $out.Contains($n)) { [void]$out.Add($n) } }
|    }
|    if ($out.Count -eq 0 -and $Dcr.properties.streamDeclarations) {
|        foreach ($p in $Dcr.properties.streamDeclarations.PSObject.Properties) { [void]$out.Add([string]$p.Name) }
|    }
|    return $out.ToArray()
|}
|
|function Test-SILogDcrFeedsOtherTable {
|    <# PURE. $true when the rule exists, writes at least one stream, and none of its streams is this table's. #>
|    param([AllowNull()]$Dcr, [Parameter(Mandatory)][string]$TableName)
|    $streams = @(Get-SILogDcrStreams -Dcr $Dcr)
|    if ($streams.Count -eq 0) { return $false }
|    $t = $TableName -replace '_CL$', ''
|    $mine = @(('Custom-' + $t + '_CL'), (Get-SILogStreamName -TableName $t))
|    foreach ($s in $streams) { if ($mine -contains $s) { return $false } }
|    return $true
|}
|
|function Get-SILogDcrStreamColumns {
|    <# PURE. The column names the rule declares for this table's stream (empty when it declares none). #>
|    param([AllowNull()]$Dcr, [Parameter(Mandatory)][string]$TableName)
|    if ($null -eq $Dcr -or $null -eq $Dcr.properties -or -not $Dcr.properties.streamDeclarations) { return @() }
|    $t = $TableName -replace '_CL$', ''
|    foreach ($s in @(('Custom-' + $t + '_CL'), (Get-SILogStreamName -TableName $t))) {
|        $p = $Dcr.properties.streamDeclarations.PSObject.Properties[$s]
|        if ($p) { return @(@($p.Value.columns) | Where-Object { $_ } | ForEach-Object { [string]$_.name }) }
|    }
|    return @()
|}
|
|function Get-SILogAddedColumns {
|    <# PURE. Columns in -After that -Before did not have. #>
|    param([AllowEmptyCollection()][string[]]$Before = @(), [AllowEmptyCollection()][string[]]$After = @())
|    return @(@($After) | Where-Object { $_ -and (@($Before) -notcontains $_) })
|}
|
|function Get-SILogAlternateDcrName {
|    <# PURE. A distinct, deterministic rule name for this install: '<name>-<resource group>', or '<name>-<8-character
|       hash of the resource group>' when that would pass 60 characters -- the rule the profilers' collision rename
|       already uses, so every run derives the same name. #>
|    param([Parameter(Mandatory)][string]$DcrName, [Parameter(Mandatory)][string]$ResourceGroup)
|    $rgClean = ($ResourceGroup -replace '[^a-zA-Z0-9-]', '-').ToLowerInvariant().Trim('-')
|    $name = "$DcrName-$rgClean"
|    if ($name.Length -gt 60) {
|        $sha = [System.Security.Cryptography.SHA1]::Create()
|        try { $h = $sha.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($ResourceGroup.ToLowerInvariant())) } finally { $sha.Dispose() }
|        $name = "$DcrName-" + (([BitConverter]::ToString($h) -replace '-', '').Substring(0, 8).ToLowerInvariant())
|    }
|    return $name
|}
|
|function Get-SILogDcrRepurposeMessage {
|    <# The one sentence a refused rule produces. #>
|    param([string]$DcrName, [string]$ResourceGroup, [string[]]$Streams, [string]$TableName)
|    $feeds = (@($Streams) | ForEach-Object { $_ -replace '^Custom-', '' }) -join ', '
|    ("The data collection rule '{0}' (resource group '{1}') already sends data to {2}. It is left unchanged -- changing it to send {3}_CL would stop the data it carries now. Give {3}_CL a rule of its own: set this table's data collection rule name in config\SecurityInsight.custom.ps1 to a new name (it is created automatically)." -f `
|        $DcrName, $ResourceGroup, $feeds, ($TableName -replace '_CL$', ''))
|}
|
|function Get-SILogDcrState {
|    <#
|        The rule as Azure has it NOW (never from the run cache): Known = $false when it cannot be read (no subscription /
|        resource group configured, or the read failed); else Dcr = the rule, or $null when it does not exist.
|    #>
|    param([string]$DcrName, [string]$DcrResourceGroup, [string]$WorkspaceResourceId, $Bound)
|    $scope = Get-SILogIngestScope -WorkspaceResourceId $WorkspaceResourceId -DcrResourceGroup $DcrResourceGroup
|    if (-not $DcrName -or -not $scope.Subscription -or -not $scope.DcrRg) { return [pscustomobject]@{ Known = $false; Dcr = $null; ResourceGroup = $scope.DcrRg } }
|    try {
|        $auth = Resolve-SILogIngestAuth -Bound $Bound
|        $d = Invoke-SILogArm -Path "/subscriptions/$($scope.Subscription)/resourceGroups/$($scope.DcrRg)/providers/Microsoft.Insights/dataCollectionRules/$DcrName" `
|                 -ApiVersion (Get-SILogArmApiVersion Dcr) -Auth $auth -AllowNotFound -NoCache
|        return [pscustomobject]@{ Known = $true; Dcr = $d; ResourceGroup = $scope.DcrRg }
|    } catch {
|        Write-Verbose ("data collection rule '{0}' could not be read before the update: {1}" -f $DcrName, $_.Exception.Message)
|        return [pscustomobject]@{ Known = $false; Dcr = $null; ResourceGroup = $scope.DcrRg }
|    }
|}
|
|function Resolve-SILogDcrNameForTable {
|    <#
|        The rule name this table should post through: -DcrName, unless that rule exists and feeds ANOTHER table -- then
|        Get-SILogAlternateDcrName (when that one is free or already this table's). When the alternate is taken too, the
|        original name is returned and the wrapper refuses it with a clear message. Unknown (cannot be read) -> unchanged.
|        Returns Name + Reason (empty when unchanged).
|    #>
|    param([Parameter(Mandatory)][string]$DcrName, [string]$DcrResourceGroup, [Parameter(Mandatory)][string]$TableName, [string]$WorkspaceResourceId, $Bound)
|    $st = Get-SILogDcrState -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -WorkspaceResourceId $WorkspaceResourceId -Bound $Bound
|    if (-not $st.Known -or -not $st.Dcr -or -not (Test-SILogDcrFeedsOtherTable -Dcr $st.Dcr -TableName $TableName)) {
|        return [pscustomobject]@{ Name = $DcrName; Reason = '' }
|    }
|    $alt = Get-SILogAlternateDcrName -DcrName $DcrName -ResourceGroup ([string]$st.ResourceGroup)
|    $st2 = Get-SILogDcrState -DcrName $alt -DcrResourceGroup $DcrResourceGroup -WorkspaceResourceId $WorkspaceResourceId -Bound $Bound
|    if ($st2.Known -and $st2.Dcr -and (Test-SILogDcrFeedsOtherTable -Dcr $st2.Dcr -TableName $TableName)) {
|        return [pscustomobject]@{ Name = $DcrName; Reason = '' }
|    }
|    $feeds = (@(Get-SILogDcrStreams -Dcr $st.Dcr) | ForEach-Object { $_ -replace '^Custom-', '' }) -join ', '
|    [pscustomobject]@{
|        Name   = $alt
|        Reason = ("the data collection rule '{0}' already sends data to {1} and is left unchanged; {2}_CL uses its own rule '{3}'." -f $DcrName, $feeds, ($TableName -replace '_CL$', ''), $alt)
|    }
|}
|
|function Start-SILogDcrWatch {
|    <# Before a rule is created / updated: refuse a rule that feeds another table; remember the columns it declares. #>
|    param([string]$DcrName, [string]$DcrResourceGroup, [string]$TableName, [string]$WorkspaceResourceId, $Bound)
|    if (-not $DcrName -or -not $TableName) { return $null }
|    $b = @{}; if ($Bound) { foreach ($k in @($Bound.Keys)) { if ($k -notin 'Data', 'SchemaSourceObject') { $b[$k] = $Bound[$k] } } }
|    $st = Get-SILogDcrState -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -WorkspaceResourceId $WorkspaceResourceId -Bound $b
|    if (-not $st.Known) { return $null }
|    if ($st.Dcr -and (Test-SILogDcrFeedsOtherTable -Dcr $st.Dcr -TableName $TableName)) {
|        throw (Get-SILogDcrRepurposeMessage -DcrName $DcrName -ResourceGroup ([string]$st.ResourceGroup) -Streams @(Get-SILogDcrStreams -Dcr $st.Dcr) -TableName $TableName)
|    }
|    [pscustomobject]@{
|        DcrName = $DcrName; DcrResourceGroup = $DcrResourceGroup; TableName = ($TableName -replace '_CL$', ''); WorkspaceResourceId = $WorkspaceResourceId
|        Bound = $b; Existed = [bool]$st.Dcr; Before = @(Get-SILogDcrStreamColumns -Dcr $st.Dcr -TableName $TableName)
|    }
|}
|
|function Complete-SILogDcrWatch {
|    <# After the update: columns an EXISTING rule gained are noted for Confirm-SILogNewColumns. Never throws. #>
|    param($Watch)
|    if (-not $Watch -or -not $Watch.Existed) { return }
|    # The run-health record does not check itself: it is the record a check would report into.
|    if ($Watch.TableName -ieq 'SI_RunHealth') { return }
|    try {
|        $st = Get-SILogDcrState -DcrName $Watch.DcrName -DcrResourceGroup $Watch.DcrResourceGroup -WorkspaceResourceId $Watch.WorkspaceResourceId -Bound $Watch.Bound
|        if (-not $st.Known -or -not $st.Dcr) { return }
|        $added = @(Get-SILogAddedColumns -Before $Watch.Before -After @(Get-SILogDcrStreamColumns -Dcr $st.Dcr -TableName $Watch.TableName))
|        if ($added.Count -eq 0) { return }
|        if (-not ($global:SI_LogIngestNewColumns -is [hashtable])) { $global:SI_LogIngestNewColumns = @{} }
|        $key = $Watch.DcrName.ToLowerInvariant()
|        $ws = if ($Watch.WorkspaceResourceId) { $Watch.WorkspaceResourceId } else { [string]$global:SI_WorkspaceResourceId }
|        if ($global:SI_LogIngestNewColumns.ContainsKey($key)) {
|            $prev = $global:SI_LogIngestNewColumns[$key]
|            $added = @(@($prev.Columns) + @($added) | Select-Object -Unique)
|        }
|        $global:SI_LogIngestNewColumns[$key] = [pscustomobject]@{ Table = $Watch.TableName; Columns = $added; WorkspaceResourceId = $ws; AddedAt = [datetime]::UtcNow }
|    } catch { Write-Verbose ("new-column check skipped: {0}" -f $_.Exception.Message) }
|}
|
|function Get-SILogColumnsWithValues {
|    <# PURE. Of -Columns, those holding a non-empty value in at least one row (only those can be checked). #>
|    param([AllowEmptyCollection()][object[]]$Rows = @(), [AllowEmptyCollection()][string[]]$Columns = @())
|    $out = New-Object System.Collections.Generic.List[string]
|    foreach ($c in @($Columns)) {
|        foreach ($r in @($Rows)) {
|            if ($null -eq $r) { continue }
|            $v = if ($r -is [System.Collections.IDictionary]) { $r[$c] } elseif ($r.PSObject.Properties[$c]) { $r.$c } else { $null }
|            if ($null -ne $v -and -not [string]::IsNullOrWhiteSpace([string]$v)) { [void]$out.Add($c); break }
|        }
|    }
|    return $out.ToArray()
|}
|
|function Get-SILogRowColumnNames {
|    <# PURE. Every column name the rows carry (first-seen order, TimeGenerated left out: Azure sets it). #>
|    param([AllowEmptyCollection()][object[]]$Rows = @())
|    $seen = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    $out = New-Object System.Collections.Generic.List[string]
|    foreach ($r in @($Rows)) {
|        if ($null -eq $r) { continue }
|        $names = if ($r -is [System.Collections.IDictionary]) { @($r.Keys | ForEach-Object { [string]$_ }) } else { @($r.PSObject.Properties | ForEach-Object { $_.Name }) }
|        foreach ($n in $names) { if ($n -and $n -ne 'TimeGenerated' -and $seen.Add($n)) { [void]$out.Add($n) } }
|    }
|    return $out.ToArray()
|}
|
|function Get-SILogRowsCollectionTime {
|    <# PURE. The run's CollectionTime from the first row that carries one, as UTC; $null when no row does. #>
|    param([AllowEmptyCollection()][object[]]$Rows = @())
|    foreach ($r in @($Rows)) {
|        if ($null -eq $r) { continue }
|        $v = if ($r -is [System.Collections.IDictionary]) { $r['CollectionTime'] } elseif ($r.PSObject.Properties['CollectionTime']) { $r.CollectionTime } else { $null }
|        if ($null -eq $v -or [string]::IsNullOrWhiteSpace([string]$v)) { continue }
|        if ($v -is [datetime]) { if ($v.Kind -eq [DateTimeKind]::Local) { return $v.ToUniversalTime() }; return [datetime]::SpecifyKind($v, [DateTimeKind]::Utc) }
|        $d = [datetime]::MinValue
|        $styles = [Globalization.DateTimeStyles]::AssumeUniversal -bor [Globalization.DateTimeStyles]::AdjustToUniversal
|        if ([datetime]::TryParse([string]$v, [Globalization.CultureInfo]::InvariantCulture, $styles, [ref]$d)) { return $d }
|    }
|    return $null
|}
|
|function Get-SILogColumnCheckKql {
|    <# PURE. Rows of this run in the table, and how many carry a value in each new column (C0, C1, ... in -Columns order). #>
|    param([Parameter(Mandatory)][string]$TableName, [Parameter(Mandatory)][string[]]$Columns, [AllowNull()]$CollectionTime, [AllowNull()]$PostedSince)
|    $t = ($TableName -replace '_CL$', '') -replace '[^A-Za-z0-9_]', ''
|    $agg = for ($i = 0; $i -lt $Columns.Count; $i++) {
|        'C{0} = countif(isnotempty(tostring(column_ifexists("{1}", ""))))' -f $i, ($Columns[$i] -replace '[^A-Za-z0-9_]', '')
|    }
|    $filter = if ($CollectionTime) {
|        $ct = ([datetime]$CollectionTime).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.fffZ', [Globalization.CultureInfo]::InvariantCulture)
|        "| where TimeGenerated > ago(2d)`n| where CollectionTime between (datetime($ct) - 2s .. datetime($ct) + 2s)"
|    } else {
|        $since = ([datetime]$PostedSince).ToUniversalTime().AddMinutes(-1).ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture)
|        "| where TimeGenerated >= datetime($since)"
|    }
|    "{0}_CL`n{1}`n| summarize Rows = count(), {2}" -f $t, $filter, ($agg -join ', ')
|}
|
|function Get-SILogColumnCheckVerdict {
|    <#
|        PURE. One result row of Get-SILogColumnCheckKql -> Verdict:
|          stored      -- rows arrived and every new column holds values
|          not-stored  -- rows arrived and a new column is empty on all of them (Missing names which)
|          not-landed  -- no row of this run is queryable yet
|    #>
|    param([AllowNull()]$Result, [Parameter(Mandatory)][string[]]$Columns)
|    $get = { param($n) if ($null -eq $Result) { 0 } elseif ($Result -is [System.Collections.IDictionary]) { [long]$Result[$n] } elseif ($Result.PSObject.Properties[$n]) { [long]$Result.$n } else { 0 } }
|    $rows = & $get 'Rows'
|    if ($rows -le 0) { return [pscustomobject]@{ Verdict = 'not-landed'; Rows = 0; Missing = @($Columns) } }
|    $missing = @(for ($i = 0; $i -lt $Columns.Count; $i++) { if ((& $get ('C' + $i)) -le 0) { $Columns[$i] } })
|    if ($missing.Count -gt 0) { return [pscustomobject]@{ Verdict = 'not-stored'; Rows = $rows; Missing = $missing } }
|    [pscustomobject]@{ Verdict = 'stored'; Rows = $rows; Missing = @() }
|}
|
|function Invoke-SILogLaQuery {
|    <# One Log Analytics query as the run's identity (the workspace's id read through ARM). Returns the first table's
|       rows as objects. Throws on failure. #>
|    param([Parameter(Mandatory)][string]$WorkspaceResourceId, [Parameter(Mandatory)][string]$Query, $Bound)
|    $auth = Resolve-SILogIngestAuth -Bound $Bound
|    $ws = Invoke-SILogArm -Path $WorkspaceResourceId -ApiVersion (Get-SILogArmApiVersion Table) -Auth $auth
|    $cid = if ($ws -and $ws.properties) { [string]$ws.properties.customerId } else { '' }
|    if (-not $cid) { throw 'the Log Analytics workspace id could not be read' }
|    $r = Invoke-SILogIngestRequest -Method POST -Uri ('https://api.loganalytics.io/v1/workspaces/{0}/query' -f $cid) -Body (@{ query = $Query } | ConvertTo-Json -Compress) `
|             -Resource 'https://api.loganalytics.io/' -Auth $auth -MaxAttempts 3 -What 'Log Analytics query'
|    $j = $r.Content | ConvertFrom-Json
|    $tbl = @($j.tables)[0]
|    if (-not $tbl) { return @() }
|    $names = @(@($tbl.columns) | ForEach-Object { [string]$_.name })
|    foreach ($row in @($tbl.rows)) {
|        $o = [ordered]@{}
|        for ($i = 0; $i -lt $names.Count; $i++) { $o[$names[$i]] = @($row)[$i] }
|        [pscustomobject]$o
|    }
|}
|
|function Wait-SILogColumnsStored {
|    <#
|        Asks Log Analytics, until this run's rows have arrived, whether the new columns hold their values. Polls at 30 s,
|        then 60 s, then every 120 s; stops as soon as the answer is known (stored, or every row arrived with a column
|        empty) or after -WindowSec (default 900: Azure's ingestion delay is normally seconds to a few minutes, so rows
|        that are still missing after 15 minutes are reported, not waited for). A query that fails ends the check.
|    #>
|    param([Parameter(Mandatory)][string]$WorkspaceResourceId, [Parameter(Mandatory)][string]$TableName, [Parameter(Mandatory)][string[]]$Columns,
|          [AllowNull()]$CollectionTime, [AllowNull()]$PostedSince, [int]$ExpectedRows = 1, $Bound, [int]$WindowSec = 0)
|    if ($WindowSec -le 0) { $WindowSec = 900; $o = 0; if ([int]::TryParse([string]$global:SI_LogIngest_NewColumnCheckSec, [ref]$o) -and $o -gt 0) { $WindowSec = $o } }
|    $kql = Get-SILogColumnCheckKql -TableName $TableName -Columns $Columns -CollectionTime $CollectionTime -PostedSince $PostedSince
|    $waited = 0; $step = 30
|    $last = [pscustomobject]@{ Verdict = 'not-landed'; Rows = 0; Missing = @($Columns) }
|    while ($true) {
|        Start-Sleep -Seconds $step
|        $waited += $step
|        try {
|            $res = @(Invoke-SILogLaQuery -WorkspaceResourceId $WorkspaceResourceId -Query $kql -Bound $Bound)
|            $last = Get-SILogColumnCheckVerdict -Result $(if ($res.Count) { $res[0] } else { $null }) -Columns $Columns
|        } catch {
|            $last = [pscustomobject]@{ Verdict = 'unverified'; Rows = 0; Missing = @($Columns); Detail = $_.Exception.Message }
|            break
|        }
|        if ($last.Verdict -eq 'stored') { break }
|        if ($last.Verdict -eq 'not-stored' -and $last.Rows -ge $ExpectedRows) { break }
|        if ($waited -ge $WindowSec) { break }
|        $step = [Math]::Min(120, $step * 2)
|    }
|    $last | Add-Member -NotePropertyName WaitedSec -NotePropertyValue $waited -Force
|    return $last
|}
|
|function Add-SILogIngestNote {
|    <# Something a publish could not deliver in full, for the run's outcome (Get-SIRunOutcome). #>
|    # -Kind 'column-lag' (#414): only NEW, non-key columns were not stored yet (Azure's propagation delay) -- the rows and
|    # their key columns are there, so a Risk Analysis run says it as a warning and is NOT partial for it.
|    param([Parameter(Mandatory)][string]$Table, [string[]]$Columns = @(), [Parameter(Mandatory)][string]$Message, [string]$Kind = 'incomplete')
|    if (-not ($global:SI_LogIngestNotes -is [System.Collections.Generic.List[object]])) { $global:SI_LogIngestNotes = New-Object System.Collections.Generic.List[object] }
|    [void]$global:SI_LogIngestNotes.Add([pscustomobject]@{ Table = $Table; Columns = @($Columns); Message = $Message; Kind = $Kind })
|}
|
|function Get-SILogIngestNoteKind {
|    <#
|        PURE. 'column-lag' when a 'not-stored' verdict misses only non-key columns; else 'incomplete'.
|        #414 / #294: the KEY columns are the ones a row cannot be placed or read without. A new key column that was not
|        stored is a real loss (the data sync refuses such rows); any other new column not stored yet is propagation lag.
|    #>
|    param([string]$Verdict, [string[]]$Missing = @())
|    $keys = @('CollectionTime', 'ConfigurationId', 'AssetId', 'AssetName', 'ReportName', 'SecuritySeverity', 'CriticalityTier', 'RiskScoreTotal', 'SolutionVersion')
|    if ($Verdict -ne 'not-stored' -or -not @($Missing).Count) { return 'incomplete' }
|    foreach ($m in @($Missing)) { if ($keys -contains ([string]$m).Trim()) { return 'incomplete' } }
|    'column-lag'
|}
|
|function Get-SILogIngestNotes {
|    if ($global:SI_LogIngestNotes -is [System.Collections.Generic.List[object]]) { return $global:SI_LogIngestNotes.ToArray() }
|    return @()
|}
|
|function Reset-SILogIngestNotes {
|    <# At the start of a run: notes and pending column checks belong to ONE run. #>
|    $global:SI_LogIngestNotes = New-Object System.Collections.Generic.List[object]
|    $global:SI_LogIngestNewColumns = @{}
|}
|
|function Confirm-SILogNewColumns {
|    <#
|        After a post through a rule that gained columns earlier in this run: were this run's values for them STORED?
|        Not stored (or not confirmable) -> one warning that says what is missing and that the next run fills it, and a
|        note that makes the run's outcome success-partial. Never throws: the rows themselves were posted.
|    #>
|    param([string]$DcrName, [string]$TableName, [AllowNull()][array]$Data, $Bound)
|    if (-not $DcrName -or -not ($global:SI_LogIngestNewColumns -is [hashtable])) { return }
|    $key = $DcrName.ToLowerInvariant()
|    if (-not $global:SI_LogIngestNewColumns.ContainsKey($key)) { return }
|    $chg = $global:SI_LogIngestNewColumns[$key]
|    $global:SI_LogIngestNewColumns.Remove($key)
|    $table = if ($TableName) { $TableName -replace '_CL$', '' } else { [string]$chg.Table }
|    try {
|        $rows = @($Data)
|        $newCols = @(Get-SILogColumnsWithValues -Rows $rows -Columns @($chg.Columns))
|        # ring 1, 2026-10-11 -- a rule CHANGED right before the post can drop values of columns it had already (added by an
|        # earlier run or job inside Azure's propagation window), not only of the columns this run added. So once this run
|        # changed the rule, EVERY column that carries a value in the posted rows is checked; the new ones first.
|        $cols = @(Get-SILogColumnsWithValues -Rows $rows -Columns @(@($newCols) + @(Get-SILogRowColumnNames -Rows $rows) | Select-Object -Unique))
|        if ($newCols.Count -eq 0 -or $cols.Count -eq 0) { return }
|        # #475: the wait (half a minute or more) is spent ONCE per table per process -- a run that posts its records in
|        # dozens of batches gained new columns batch after batch and waited every time (customer H 2026-10-09)
|        $rcache = Get-SILogIngestRunCache
|        if (-not ($rcache.ConfirmedTables -is [hashtable])) { $rcache.ConfirmedTables = @{} }
|        $tk = $table.ToLowerInvariant()
|        if ($rcache.ConfirmedTables.ContainsKey($tk)) {
|            Write-Host (" [INFO] {0}_CL gained {1} more new column(s) ({2}); this run checked the table's new columns once already, so these are not waited for -- the next run stores them in any case." -f $table, $newCols.Count, ($newCols -join ', '))
|            return
|        }
|        $rcache.ConfirmedTables[$tk] = $true
|        $b = @{}; if ($Bound) { foreach ($k in @($Bound.Keys)) { if ($k -ne 'Data') { $b[$k] = $Bound[$k] } } }
|        Write-Host (" [INFO] {0}_CL gained {1} new column(s) in this run ({2}). Azure takes a while to start storing a new column, so this run checks that the values of every column it posted ({3}) arrived ..." -f $table, $newCols.Count, ($newCols -join ', '), $cols.Count)
|        $res = Wait-SILogColumnsStored -WorkspaceResourceId ([string]$chg.WorkspaceResourceId) -TableName $table -Columns $cols `
|                   -CollectionTime (Get-SILogRowsCollectionTime -Rows $rows) -PostedSince ([datetime]::UtcNow.AddSeconds(-60)) -ExpectedRows $rows.Count -Bound $b
|        if ($res.Verdict -eq 'stored') {
|            Write-Host (" [OK]   {0}_CL: the new column(s) hold this run's values." -f $table)
|            return
|        }
|        $msg = switch ($res.Verdict) {
|            'not-stored' { "{0}_CL: the data collection rule was changed in this run and Azure was not yet storing every column when the rows arrived: this run's values for {1} are missing. The rows are there; the next run stores these columns." -f $table, (@($res.Missing) -join ', ') }
|            'not-landed' { "{0}_CL gained new column(s) in this run ({1}) and this run's rows were not queryable within {2} minutes, so it is not known whether those columns were stored." -f $table, ($cols -join ', '), [int]($res.WaitedSec / 60) }
|            default      { "{0}_CL gained new column(s) in this run ({1}) and it could not be checked whether this run's values were stored ({2})." -f $table, ($cols -join ', '), $res.Detail }
|        }
|        Write-Warning $msg
|        # the run's outcome is judged on the columns this run ADDED (as before); a column the rule already had that read
|        # back empty is said (the warning above) but only ever counts as propagation lag
|        $missNew = @(@($res.Missing) | Where-Object { $newCols -contains $_ })
|        $kind = 'column-lag'
|        if ([string]$res.Verdict -ne 'not-stored') { $kind = 'incomplete' }
|        elseif ($missNew.Count -gt 0) { $kind = Get-SILogIngestNoteKind -Verdict 'not-stored' -Missing $missNew }
|        Add-SILogIngestNote -Table $table -Columns $cols -Message $msg -Kind $kind
|    } catch {
|        $msg = ("{0}_CL gained new column(s) in this run and it could not be checked whether this run's values were stored ({1})." -f $table, $_.Exception.Message)
|        Write-Warning $msg
|        Add-SILogIngestNote -Table $table -Message $msg
|    }
|}
|
|# =====================================================================================================================
|#  THE RULE MUST DECLARE EVERY COLUMN OF THE DATA -- both engines (#294)
|#
|#  Azure stores only the columns a data collection rule DECLARES: every other value of a posted row is dropped, and the
|#  post still answers 204. Found live 2026-10-05 on ring 1: a Risk Analysis Detailed run posted 14,624 rows and only
|#  AssetName, AssetId, the report name and 8 more columns arrived -- CollectionTime, ConfigurationId, SecuritySeverity,
|#  CriticalityTier, RiskScoreTotal and SolutionVersion were EMPTY on every row, and the run logged SUCCESS. The chain:
|#    1. the run used the default rule name (its configuration had not reached the job), a rule that did not exist yet;
|#    2. AzLogDcrIngestPS creates a new rule in two steps -- first with the data's FIRST 11 columns, then with all of
|#       them. The second step was refused (InvalidTransformOutput: a column the data reads as an object, the existing
|#       table holds as text), so the rule was left with 11 columns;
|#    3. on the next run the module looked the rule up BY NAME across the tenant, found another install's same-named
|#       rule with every column, concluded nothing was missing, and the rows went through the 11-column rule.
|#  Set-SILogDcrRest stops step 2 (a new rule for an existing table is declared from the TABLE, with its
|#  types); Assert-SILogDcrCoversData stops step 3 for good: after every table/rule update it reads THE rule this install
|#  posts through (in the configured scope, never by name across the tenant), adds from the table any column of the data
|#  the rule does not declare, and REFUSES the post when a column of the data still is not declared.
|# =====================================================================================================================
|
|function Get-SILogBoundAuth {
|    <# The sign-in arguments of a wrapper call (what Set-SILogDcrRest / Resolve-SILogIngestAuth take), nothing else. #>
|    param($Bound)
|    $b = @{}
|    if ($null -eq $Bound) { return $b }
|    foreach ($k in 'AzAppId', 'AzAppSecret', 'AzAppCertificateThumbprint', 'AzAppCertificateStoreLocation', 'UseManagedIdentity', 'ManagedIdentityClientId', 'TenantId') {
|        if ($Bound.ContainsKey($k) -and $null -ne $Bound[$k] -and "$($Bound[$k])" -ne '') { $b[$k] = $Bound[$k] }
|    }
|    $b
|}
|
|function Get-SILogDataColumnNames {
|    <#
|        PURE. The columns a set of rows carries: the union over EVERY row (first-seen order, names compared without
|        letter case), without TimeGenerated and Log Analytics' own standard columns, and only names a Log Analytics
|        column can have (a name the ingest path drops before posting is not a column of the posted data).
|    #>
|    param([AllowNull()][AllowEmptyCollection()][object[]]$Rows = @())
|    $std = @('TimeGenerated', 'TenantId', 'Type', '_ResourceId', '_SubscriptionId', 'SourceSystem', 'MG', 'ManagementGroupName', '_BilledSize', '_IsBillable', '_ItemId', '_TimeReceived')
|    $seen = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    $out = New-Object System.Collections.Generic.List[string]
|    foreach ($r in @($Rows)) {
|        if ($null -eq $r) { continue }
|        $names = if ($r -is [System.Collections.IDictionary]) { @($r.Keys) } else { @($r.PSObject.Properties | ForEach-Object { $_.Name }) }
|        foreach ($n in $names) {
|            $s = [string]$n
|            if (-not $s -or $s -notmatch '^[A-Za-z][A-Za-z0-9_]*$' -or ($std -contains $s)) { continue }
|            if ($s.Length -gt 45) { $s = $s.Substring(0, 45) }   # the column name repair cuts a longer name to 45
|            if ($seen.Add($s)) { [void]$out.Add($s) }
|        }
|    }
|    return $out.ToArray()
|}
|
|function Get-SILogNewRuleColumns {
|    <#
|        PURE. The stream declaration of a NEW rule: the table's columns with the table's types when the table exists (then
|        each column of -SchemaSourceObject the table does not have, with its own type); else -SchemaSourceObject.
|        TimeGenerated is never declared (the rule's transform sets it).
|    #>
|    param([AllowNull()]$Table, [AllowNull()][AllowEmptyCollection()][object[]]$SchemaSourceObject = @())
|    $out = New-Object System.Collections.Generic.List[object]
|    $seen = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    $add = { param($n, $t) $s = [string]$n; if ($s -and $s -ne 'TimeGenerated' -and $seen.Add($s)) { [void]$out.Add([ordered]@{ name = $s; type = [string]$t }) } }
|    if ($null -ne $Table -and $Table.properties -and $Table.properties.schema) {
|        foreach ($c in @($Table.properties.schema.columns)) { if ($c) { & $add $c.name $c.type } }
|    }
|    foreach ($c in @($SchemaSourceObject)) { if ($c) { & $add $c.name $c.type } }
|    return $out.ToArray()
|}
|
|function Get-SILogDcrCoverageGap {
|    <#
|        PURE. Which of -Columns the rule does NOT declare for this table's stream: Missing (all of them), InTable (those
|        the table has -- the rule can be given them from the table) and NotInTable (those the table does not have).
|    #>
|    param([AllowNull()]$Dcr, [Parameter(Mandatory)][string]$TableName, [AllowEmptyCollection()][string[]]$Columns = @(), [AllowNull()]$Table)
|    $declared = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    foreach ($n in @(Get-SILogDcrStreamColumns -Dcr $Dcr -TableName $TableName)) { [void]$declared.Add([string]$n) }
|    $inTable = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    if ($null -ne $Table -and $Table.properties -and $Table.properties.schema) {
|        foreach ($c in @($Table.properties.schema.columns)) { if ($c) { [void]$inTable.Add([string]$c.name) } }
|    }
|    $missing = @(@($Columns) | Where-Object { $_ -and -not $declared.Contains([string]$_) })
|    [pscustomobject]@{
|        Missing    = $missing
|        InTable    = @($missing | Where-Object { $inTable.Contains([string]$_) })
|        NotInTable = @($missing | Where-Object { -not $inTable.Contains([string]$_) })
|    }
|}
|
|function Assert-SILogDcrCoversData {
|    <#
|        After a table/rule update: THE rule this install posts through (read in the configured scope) must declare every
|        column of -Data. Columns it lacks that the table has are added from the table (Set-SILogDcrRest, additive); a
|        column still not declared after that REFUSES the post -- throws System.IO.InvalidDataException, because Azure
|        would store the rows without it and answer success. Columns the TABLE does not have either are said and noted
|        (the run is partial), not refused: the table update is what failed there, and it says so itself.
|        Nothing is checked when schema management is off for this machine (the same rule the module applies) or the
|        rule cannot be read (said with -Verbose; Known = $false). Returns @{ Verdict; Added; Missing }.
|    #>
|    param([string]$DcrName, [string]$DcrResourceGroup, [string]$TableName, [string]$WorkspaceResourceId, [string]$DceName, [AllowNull()][array]$Data, $Bound)
|    $res = [pscustomobject]@{ Verdict = 'skipped'; Added = @(); Missing = @() }
|    if (-not $DcrName -or -not $TableName) { return $res }
|    if ($Bound) {
|        if ($Bound.ContainsKey('EnableUploadViaLogHub') -and [bool]$Bound['EnableUploadViaLogHub']) { return $res }
|        if ($Bound.ContainsKey('AzLogDcrTableCreateFromAnyMachine') -and -not [bool]$Bound['AzLogDcrTableCreateFromAnyMachine']) {
|            $ref = if ($Bound.ContainsKey('AzLogDcrTableCreateFromReferenceMachine')) { @($Bound['AzLogDcrTableCreateFromReferenceMachine']) } else { @() }
|            if (-not ($env:COMPUTERNAME -and ($ref -contains $env:COMPUTERNAME))) { return $res }
|        }
|    }
|    $cols = @(Get-SILogDataColumnNames -Rows @($Data))
|    if (-not $cols.Count) { return $res }
|    $t = $TableName -replace '_CL$', ''
|    $b = Get-SILogBoundAuth -Bound $Bound
|    $st = Get-SILogDcrState -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -WorkspaceResourceId $WorkspaceResourceId -Bound $b
|    if (-not $st.Known) { $res.Verdict = 'unknown'; Write-Verbose ("data collection rule '{0}' could not be read -- its columns are not checked" -f $DcrName); return $res }
|    if (-not $st.Dcr) {
|        throw (New-Object System.IO.InvalidDataException(("The data collection rule '{0}' does not exist in resource group '{1}' after the table and rule update, so nothing is posted to {2}_CL." -f $DcrName, $st.ResourceGroup, $t)))
|    }
|    $auth = Resolve-SILogIngestAuth -Bound $b
|    $readTable = { try { Get-SILogTableRest -WorkspaceResourceId $WorkspaceResourceId -TableName $t -Auth $auth -NoCache } catch { $null } }
|    $table = & $readTable
|    $gap = Get-SILogDcrCoverageGap -Dcr $st.Dcr -TableName $t -Columns $cols -Table $table
|    if (-not @($gap.Missing).Count) { $res.Verdict = 'covered'; return $res }
|    if (@($gap.InTable).Count) {
|        Write-Host (" [WARN] the data collection rule '{0}' does not declare {1} column(s) of {2}_CL that this data carries ({3}) -- Azure would drop their values. Adding them to the rule from the table." -f `
|            $DcrName, @($gap.InTable).Count, $t, ((@($gap.InTable) | Select-Object -First 12) -join ', ')) -ForegroundColor Yellow
|        $null = Set-SILogDcrRest -SchemaSourceObject @(@($gap.InTable) | ForEach-Object { @{ name = [string]$_; type = 'string' } }) -AzLogWorkspaceResourceId $WorkspaceResourceId `
|                    -DceName $DceName -DcrResourceGroup ([string]$st.ResourceGroup) -DcrName $DcrName -TableName $t @b
|        $res.Added = @($gap.InTable)
|        $st = Get-SILogDcrState -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -WorkspaceResourceId $WorkspaceResourceId -Bound $b
|        $gap = Get-SILogDcrCoverageGap -Dcr $st.Dcr -TableName $t -Columns $cols -Table $table
|    }
|    $res.Missing = @($gap.Missing)
|    if (@($gap.InTable).Count) {
|        throw (New-Object System.IO.InvalidDataException(("The data collection rule '{0}' does not declare {1} column(s) of {2}_CL that this data carries ({3}) and they could not be added to it. Posting through it would store the rows WITHOUT those values, so nothing is posted." -f `
|            $DcrName, @($gap.InTable).Count, $t, ((@($gap.InTable) | Select-Object -First 20) -join ', '))))
|    }
|    if (@($gap.NotInTable).Count) {
|        $msg = ("{0}_CL does not have {1} column(s) this data carries ({2}), so their values are not stored by this run." -f $t, @($gap.NotInTable).Count, ((@($gap.NotInTable) | Select-Object -First 20) -join ', '))
|        Write-Warning $msg
|        Add-SILogIngestNote -Table $t -Columns @($gap.NotInTable) -Message $msg
|        $res.Verdict = 'partial'
|        return $res
|    }
|    $res.Verdict = 'repaired'
|    return $res
|}
|
|# =====================================================================================================================
|#  REST: run cache, HTTP seam, tokens
|# =====================================================================================================================
|
|function Get-SILogIngestRunCache {
|    <# Per-run (per-process) cache: tokens, ARM reads, DCR ids. Global because this file is dot-sourced at different
|       depths by different engines, and `$script:` would then be a different scope per caller. #>
|    if (-not ($global:SI_LogIngestRunCache -is [hashtable])) {
|        $global:SI_LogIngestRunCache = @{ Tokens = @{}; Arm = @{}; DcrIds = @{} }
|    }
|    return $global:SI_LogIngestRunCache
|}
|
|function Reset-SILogIngestArmCache {
|    <# After any create/update: the next read must see what was just written. #>
|    $c = Get-SILogIngestRunCache
|    $c.Arm = @{}
|}
|
|function Invoke-SILogIngestHttp {
|    <#
|        THE ONE HTTP SEAM. Every REST call in this file goes through here (tests Mock it). Never throws on an HTTP status:
|        returns @{ StatusCode; Content; RetryAfter }. A network failure (no response at all) is StatusCode 0.
|        HttpWebRequest, not Invoke-WebRequest: its error shape is the same on PS 5.1 and pwsh 7, so the body of a 4xx
|        and the Retry-After of a 429 are read the same way on both.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$Method,
|        [Parameter(Mandatory)][string]$Uri,
|        [hashtable]$Headers,
|        $Body,
|        [string]$ContentType,
|        [int]$TimeoutSec = 300
|    )
|    if ($PSVersionTable.PSEdition -ne 'Core') {
|        # Windows PowerShell 5.1 on an older .NET Framework may not offer TLS 1.2 by default; Azure requires it.
|        [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
|    }
|    $req = [System.Net.HttpWebRequest]::Create($Uri)
|    $req.Method = $Method.ToUpperInvariant()
|    $req.Timeout = $TimeoutSec * 1000
|    $req.ReadWriteTimeout = $TimeoutSec * 1000
|    $req.Accept = 'application/json'
|    if ($Headers) {
|        foreach ($k in $Headers.Keys) {
|            if ($k -eq 'Content-Type') { $req.ContentType = [string]$Headers[$k] }
|            elseif ($k -eq 'Accept')   { $req.Accept = [string]$Headers[$k] }
|            else { $req.Headers[$k] = [string]$Headers[$k] }
|        }
|    }
|    if ($ContentType) { $req.ContentType = $ContentType }
|    if ($null -ne $Body) {
|        # statements, never `= if (...) { $Body }`: an if-expression enumerates a byte array into object[]
|        [byte[]]$bytes = $null
|        if ($Body -is [byte[]]) { $bytes = $Body } else { $bytes = [System.Text.Encoding]::UTF8.GetBytes([string]$Body) }
|        $req.ContentLength = $bytes.Length
|        $s = $req.GetRequestStream()
|        try { $s.Write($bytes, 0, $bytes.Length) } finally { $s.Close() }
|    } elseif ($req.Method -in 'POST', 'PUT', 'PATCH') {
|        $req.ContentLength = 0
|    }
|    $resp = $null
|    try { $resp = $req.GetResponse() }
|    catch {
|        $we = $_.Exception
|        while ($we -and -not ($we -is [System.Net.WebException])) { $we = $we.InnerException }
|        if ($we -and $we.Response) {
|            $resp = $we.Response
|            # An HTTP status is an answer returned to the caller, not an error of this process: take the caught record
|            # back out of $Error (setup shows every new entry -- each probe printed "(404) Not Found", 2026-10-06).
|            if ($global:Error.Count -gt 0 -and [object]::ReferenceEquals($global:Error[0], $_)) { $global:Error.RemoveAt(0) }
|        }
|        else { return [pscustomobject]@{ StatusCode = 0; Content = [string]$_.Exception.Message; RetryAfter = $null } }
|    }
|    try {
|        $text = ''
|        $rs = $resp.GetResponseStream()
|        if ($rs) { $sr = New-Object System.IO.StreamReader($rs); try { $text = $sr.ReadToEnd() } finally { $sr.Close() } }
|        return [pscustomobject]@{ StatusCode = [int]$resp.StatusCode; Content = $text; RetryAfter = [string]$resp.Headers['Retry-After'] }
|    } finally { $resp.Close() }
|}
|
|function Initialize-SILogIngestAuthHelpers {
|    <# The managed-identity and certificate token helpers live in auth/. Loaded on first need, never at file load. #>
|    # Only what is MISSING is loaded, and only that is published to the global scope (it was dot-sourced inside this
|    # function, so it would vanish on return). Something already visible -- the engine's own copy, a test's mock -- is
|    # never replaced.
|    $authDir = Join-Path (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)) 'auth'
|    # The managed-identity helper is NOT loaded here: the run's entry point loads it (the launcher config on a VM / Arc
|    # server, the container entry in a job) -- an engine never does (SIv3-ContainerIdentity). Get-SILogIngestToken
|    # says so when it is missing.
|    $want = @(
|        @{ File = 'Find-SICertificate.ps1'; Fns = @('Get-SICertificateClientToken', 'Get-SICertificateFromStore', 'Test-SICertDriveAvailable') }
|    )
|    foreach ($w in $want) {
|        $missing = @($w.Fns | Where-Object { -not (Get-Command -Name $_ -ErrorAction Ignore) })
|        if ($missing.Count -eq 0) { continue }
|        $p = Join-Path $authDir $w.File
|        if (-not (Test-Path -LiteralPath $p)) { continue }
|        . $p
|        foreach ($n in $missing) {
|            $f = Get-Command -Name $n -CommandType Function -ErrorAction Ignore
|            if ($f) { Set-Item -Path ("function:global:{0}" -f $n) -Value $f.ScriptBlock }
|        }
|    }
|}
|
|function Resolve-SILogIngestAuth {
|    <#
|        The sign-in the call site handed over (the same splat AzLogDcrIngestPS takes), as one decision:
|          ManagedIdentity -- UseManagedIdentity = $true
|          Certificate     -- AzAppId + AzAppCertificateThumbprint + TenantId
|          Secret          -- AzAppId + AzAppSecret + TenantId
|          then the run's own decision: $global:SI_UseManagedIdentity (#222) -> ManagedIdentity, else the run's own
|          sign-in (Resolve-SIAzRestAuth: what Connect-SIAzAccount recorded, else the configured identity).
|        Same precedence as the module: managed identity, then certificate, then secret.
|    #>
|    param($Bound = @{})   # a hashtable or $PSBoundParameters
|    if ($null -eq $Bound) { $Bound = @{} }
|    $g = { param($k) if ($Bound.ContainsKey($k)) { $Bound[$k] } else { $null } }
|    $mi = & $g 'UseManagedIdentity'
|    if ($null -eq $mi -and $null -ne (Get-Variable -Scope Global -Name UseManagedIdentityDefault -ValueOnly -ErrorAction Ignore)) { $mi = (Get-Variable -Scope Global -Name UseManagedIdentityDefault -ValueOnly -ErrorAction Ignore) }
|    $app = [string](& $g 'AzAppId'); $tid = [string](& $g 'TenantId')
|    $thumb = [string](& $g 'AzAppCertificateThumbprint'); $sec = [string](& $g 'AzAppSecret')
|    if ([bool]$mi) {
|        $cid = [string](& $g 'ManagedIdentityClientId'); if (-not $cid) { $cid = [string](Get-Variable -Scope Global -Name SI_UAMI_ClientId -ValueOnly -ErrorAction Ignore) }
|        return @{ Mode = 'ManagedIdentity'; ClientId = $cid }
|    }
|    if ($app -and $thumb -and $tid) { return @{ Mode = 'Certificate'; AppId = $app; TenantId = $tid; Thumbprint = ($thumb -replace '\s', '') } }
|    if ($app -and $sec -and $tid)   { return @{ Mode = 'Secret'; AppId = $app; TenantId = $tid; Secret = $sec } }
|    if ((Get-Variable -Scope Global -Name SI_UseManagedIdentity -ValueOnly -ErrorAction Ignore) -eq $true) { return @{ Mode = 'ManagedIdentity'; ClientId = [string](Get-Variable -Scope Global -Name SI_UAMI_ClientId -ValueOnly -ErrorAction Ignore) } }
|    return @{ Mode = 'Run' }
|}
|
|function Get-SILogIngestToken {
|    <#
|        A bearer token for -Resource (https://monitor.azure.com/ for ingestion, https://management.azure.com/ for ARM),
|        as the identity -Auth (Resolve-SILogIngestAuth) names:
|          ManagedIdentity -- Get-SIManagedIdentityToken (container / Azure VM / Azure Arc endpoint; its own cache)
|          Certificate     -- Get-SICertificateClientToken (JWT client assertion signed from the X509Store; no Cert: drive)
|          Secret          -- client_credentials with the secret
|          Support         -- the Invardia support session's Get-InvardiaSupportToken (#524; SI-AzRest.ps1 Get-SISupportToken)
|          Run             -- the run's own sign-in (Resolve-SIAzRestAuth, over REST; #524: never an Azure session)
|        Cached per identity + resource until 5 minutes before expiry.
|    #>
|    param([Parameter(Mandatory)][string]$Resource, [hashtable]$Auth, [switch]$ForceRefresh)
|    # the supported token hook (see SI-AzRest.ps1): consulted first when set and no explicit sign-in was handed over
|    if (-not $Auth) {
|        $tp = Get-Variable -Scope Global -Name SI_TokenProvider -ValueOnly -ErrorAction Ignore
|        if ($tp -is [scriptblock]) { $pt = [string](& $tp $Resource); if (-not [string]::IsNullOrWhiteSpace($pt)) { return $pt } }
|        $Auth = Resolve-SILogIngestAuth
|    }
|    $res = $Resource.TrimEnd('/') + '/'
|    # #524: the Invardia support session's tokens (Resolve-SIAzRestAuth's Mode 'Support') -- Invardia caches them; the
|    # tenant of each is checked against the one SI works in
|    if ($Auth.Mode -eq 'Support') { return (Get-SISupportToken -Resource $res -TenantId ([string]$Auth.TenantId) -ForceRefresh:$ForceRefresh) }
|    $cache = (Get-SILogIngestRunCache).Tokens
|    $who = switch ($Auth.Mode) { 'Certificate' { $Auth.AppId } 'Secret' { $Auth.AppId } 'ManagedIdentity' { $Auth.ClientId } default { '' } }
|    $key = '{0}|{1}|{2}' -f $Auth.Mode, $who, $res
|    if (-not $ForceRefresh -and $cache.ContainsKey($key) -and $cache[$key].ExpiresAt -gt [datetime]::UtcNow) { return $cache[$key].Token }
|
|    $token = $null; $expiresAt = [datetime]::UtcNow.AddMinutes(45)
|    # A TRANSIENT failure of the token endpoint (the managed-identity endpoint of a container, Entra) is waited out and asked
|    # again, a bounded number of times -- Microsoft's errors (Get-SITransientKind: throttled / timeout / unavailable). Any
|    # other answer (a refused sign-in, a missing certificate) fails at once, as before. The sweep of 2026-10-22: one
|    # IDENTITY_ENDPOINT blip threw through every helper's retry and failed the run.
|    if (-not (Get-Command -Name Get-SITransientKind -ErrorAction Ignore)) { . (Join-Path $PSScriptRoot 'SI-ErrorClass.ps1') }
|    $tokenAttempts = 4
|    for ($tokenTry = 1; $tokenTry -le $tokenAttempts; $tokenTry++) {
|    try {
|    switch ($Auth.Mode) {
|        'ManagedIdentity' {
|            if (-not (Get-Command -Name Get-SIManagedIdentityToken -ErrorAction Ignore)) {
|                throw 'Sign-in as a managed identity was asked for, but the managed-identity sign-in helper is not loaded in this run (its entry point loads it: the launcher configuration or the container entry).'
|            }
|            $token = Get-SIManagedIdentityToken -Resource $res -ClientId ([string]$Auth.ClientId) -ForceRefresh:$ForceRefresh
|        }
|        'Certificate' {
|            Initialize-SILogIngestAuthHelpers
|            $token = Get-SICertificateClientToken -TenantId $Auth.TenantId -ClientId $Auth.AppId -Thumbprint $Auth.Thumbprint -Resource $res
|        }
|        'Secret' {
|            $body = 'client_id={0}&scope={1}&client_secret={2}&grant_type=client_credentials' -f `
|                [uri]::EscapeDataString($Auth.AppId), [uri]::EscapeDataString($res.TrimEnd('/') + '/.default'), [uri]::EscapeDataString($Auth.Secret)
|            $r = Invoke-SILogIngestHttp -Method POST -Uri ('https://login.microsoftonline.com/{0}/oauth2/v2.0/token' -f $Auth.TenantId) `
|                     -Body $body -ContentType 'application/x-www-form-urlencoded'
|            if ([int]$r.StatusCode -lt 200 -or [int]$r.StatusCode -ge 300) {
|                throw ("Sign-in with the client secret failed for {0}. HTTP Status: {1} Response: {2}" -f $res, $r.StatusCode, $r.Content)
|            }
|            $j = $r.Content | ConvertFrom-Json
|            $token = [string]$j.access_token
|            $secs = 0
|            if ([int]::TryParse([string]$j.expires_in, [ref]$secs) -and $secs -gt 600) { $expiresAt = [datetime]::UtcNow.AddSeconds($secs - 300) }
|        }
|        default {
|            $t = Get-SIAzAccessToken -ResourceUrl $res -ErrorAction Stop
|            $token = if ($t.Token -is [System.Security.SecureString]) { [System.Net.NetworkCredential]::new('', $t.Token).Password } else { [string]$t.Token }
|            try { if ($t.ExpiresOn) { $e = ([DateTimeOffset]$t.ExpiresOn).UtcDateTime.AddMinutes(-5); if ($e -lt $expiresAt) { $expiresAt = $e } } } catch { }
|        }
|    }
|    break
|    } catch {
|        $kind = Get-SITransientKind -Message ([string]$_.Exception.Message)
|        if ($kind -eq 'error' -or $tokenTry -ge $tokenAttempts) { throw }
|        $wait = Get-SILogIngestRetryDelay -RetryAfter '' -Attempt $tokenTry
|        Write-Verbose ("The token for {0} ({1} sign-in) was not issued ({2}: {3}) -- asked again in {4} s ({5}/{6})." -f $res, $Auth.Mode, $kind, $_.Exception.Message, $wait, $tokenTry, $tokenAttempts)
|        Start-Sleep -Seconds $wait
|    }
|    }
|    if ([string]::IsNullOrWhiteSpace($token)) { throw ("No access token for {0} ({1} sign-in)." -f $res, $Auth.Mode) }
|    $cache[$key] = @{ Token = $token; ExpiresAt = $expiresAt }
|    return $token
|}
|
|function Get-SILogIngestRetryDelay {
|    <# Seconds to wait before retry -Attempt: the server's Retry-After (seconds or an HTTP date) when it sent one,
|       else exponential (2, 4, 8 ... capped at 60). Never more than 10 minutes: a wait the server asks for had no upper
|       limit, and a run that waits says nothing meanwhile (the retry after it either works or is the answer). #>
|    param([string]$RetryAfter, [int]$Attempt)
|    $s = 0
|    if ($RetryAfter) {
|        if ([int]::TryParse($RetryAfter.Trim(), [ref]$s)) { return [Math]::Min(600, [Math]::Max(1, $s)) }
|        $d = [datetime]::MinValue
|        if ([datetime]::TryParse($RetryAfter, [System.Globalization.CultureInfo]::InvariantCulture, [System.Globalization.DateTimeStyles]::AdjustToUniversal, [ref]$d)) {
|            return [int][Math]::Min(600, [Math]::Max(1, [Math]::Ceiling(($d - [datetime]::UtcNow).TotalSeconds)))
|        }
|    }
|    return [int][Math]::Min(60, [Math]::Pow(2, $Attempt))
|}
|
|function Invoke-SILogIngestRequest {
|    <#
|        One authenticated REST call with the retry rule (CLAUDE.md working rule 4):
|          429 / 408 / 5xx / no response -> PLATFORM: wait (Retry-After when sent) and retry in-run
|          401 once                      -> the token is refreshed and the call repeated once
|          404 with -AllowNotFound       -> $null (a lookup that found nothing)
|          any other 4xx                 -> FAIL FAST, the response body in the error: re-sending an invalid request
|                                           burns time and fails identically
|        Returns the response object (StatusCode / Content).
|    #>
|    param(
|        [string]$Method = 'GET',
|        [Parameter(Mandatory)][string]$Uri,
|        $Body,
|        [string]$ContentType = 'application/json',
|        [hashtable]$Headers,
|        [string]$Resource = 'https://management.azure.com/',
|        [hashtable]$Auth,
|        [switch]$AllowNotFound,
|        [int]$MaxAttempts = 6,
|        [string]$What = 'Azure Resource Manager request'
|    )
|    $refreshed = $false; $forceNext = $false
|    for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) {
|        $token = Get-SILogIngestToken -Resource $Resource -Auth $Auth -ForceRefresh:$forceNext
|        $forceNext = $false
|        $h = @{ 'Authorization' = ('Bearer ' + $token) }
|        if ($Headers) { foreach ($k in $Headers.Keys) { $h[$k] = $Headers[$k] } }
|        $r = Invoke-SILogIngestHttp -Method $Method -Uri $Uri -Headers $h -Body $Body -ContentType $ContentType
|        $code = [int]$r.StatusCode
|        if ($code -ge 200 -and $code -lt 300) { return $r }
|        if ($code -eq 404 -and $AllowNotFound) { return $null }
|        if ($code -eq 401 -and -not $refreshed) { $refreshed = $true; $forceNext = $true; continue }
|        $transient = ($code -eq 0 -or $code -eq 408 -or $code -eq 429 -or $code -ge 500)
|        if ($transient -and $attempt -lt $MaxAttempts) {
|            $wait = Get-SILogIngestRetryDelay -RetryAfter ([string]$r.RetryAfter) -Attempt $attempt
|            Write-Verbose ("{0}: HTTP {1}, retrying in {2}s (attempt {3}/{4})" -f $What, $code, $wait, $attempt, $MaxAttempts)
|            # SAID, not only in the verbose stream (which the publish path switches off): a call that got no answer can
|            # have taken 5 minutes already, and six of them in a row were half an hour without one line in the run log
|            if ($code -eq 0 -or $wait -ge 30) {
|                Write-Host (" [INFO] {0}: {1} -- trying again in {2} second(s) (attempt {3} of {4})" -f $What, $(if ($code -eq 0) { 'no answer from Azure' } else { 'Azure answered HTTP {0}' -f $code }), $wait, $attempt, $MaxAttempts)
|            }
|            Start-Sleep -Seconds $wait
|            continue
|        }
|        throw ("{0} failed. HTTP Status: {1} Response: {2}" -f $What, $code, $r.Content)
|    }
|    throw ("{0} failed after {1} attempts." -f $What, $MaxAttempts)
|}
|
|# =====================================================================================================================
|#  REST: ARM reads/writes, scoped lookups
|# =====================================================================================================================
|
|function Get-SILogArmApiVersion {
|    <# ARM api-versions this file uses (a function, not a variable: the file is dot-sourced at different depths). #>
|    param([Parameter(Mandatory)][ValidateSet('Dce', 'Dcr', 'Table', 'Role')][string]$Kind)
|    switch ($Kind) { 'Dce' { '2022-06-01' } 'Dcr' { '2022-06-01' } 'Table' { '2022-10-01' } 'Role' { '2022-04-01' } }
|}
|
|function Invoke-SILogArm {
|    <# ARM call -> parsed JSON (or $null for a 404 with -AllowNotFound). GETs are cached per run; any write clears it. #>
|    param([string]$Method = 'GET', [Parameter(Mandatory)][string]$Path, [Parameter(Mandatory)][string]$ApiVersion, $Body, [hashtable]$Auth, [switch]$AllowNotFound, [switch]$NoCache)
|    $uri = if ($Path -match '^https://') { $Path } else { 'https://management.azure.com' + $Path + $(if ($Path -match '\?') { '&' } else { '?' }) + 'api-version=' + $ApiVersion }
|    $cache = (Get-SILogIngestRunCache).Arm
|    if ($Method -eq 'GET' -and -not $NoCache -and $cache.ContainsKey($uri)) { return $cache[$uri] }
|    $json = if ($null -ne $Body -and -not ($Body -is [string])) { $Body | ConvertTo-Json -Depth 50 -Compress } else { $Body }
|    $r = Invoke-SILogIngestRequest -Method $Method -Uri $uri -Body $json -Auth $Auth -AllowNotFound:$AllowNotFound -What ('Azure Resource Manager {0} {1}' -f $Method, ($uri -replace '\?.*$', ''))
|    $obj = $null
|    if ($r -and -not [string]::IsNullOrWhiteSpace([string]$r.Content)) { $obj = $r.Content | ConvertFrom-Json }
|    if ($Method -eq 'GET') { if (-not $NoCache) { $cache[$uri] = $obj } } else { Reset-SILogIngestArmCache }
|    return $obj
|}
|
|function Get-SILogArmList {
|    <# Every item of an ARM list, following nextLink. #>
|    param([Parameter(Mandatory)][string]$Path, [Parameter(Mandatory)][string]$ApiVersion, [hashtable]$Auth)
|    $items = New-Object 'System.Collections.Generic.List[object]'
|    $page = Invoke-SILogArm -Path $Path -ApiVersion $ApiVersion -Auth $Auth
|    while ($page) {
|        foreach ($v in @($page.value)) { if ($null -ne $v) { [void]$items.Add($v) } }
|        if ([string]::IsNullOrWhiteSpace([string]$page.nextLink)) { break }
|        $page = Invoke-SILogArm -Path ([string]$page.nextLink) -ApiVersion $ApiVersion -Auth $Auth
|    }
|    foreach ($i in $items) {
|        # the Resource Graph shape callers already read (subscriptionId / resourceGroup) -- ARM omits them
|        if ([string]$i.id -match '^/subscriptions/([^/]+)/resourceGroups/([^/]+)/') {
|            if (-not $i.PSObject.Properties['subscriptionId']) { $i | Add-Member -NotePropertyName subscriptionId -NotePropertyValue $Matches[1] }
|            if (-not $i.PSObject.Properties['resourceGroup'])  { $i | Add-Member -NotePropertyName resourceGroup -NotePropertyValue $Matches[2] }
|        }
|    }
|    return $items.ToArray()   # enumerated, like the module's list; callers wrap in @()
|}
|
|function Get-SILogIngestScope {
|    <#
|        WHERE this install's endpoint and rules live: subscription + resource groups. Lookups are by NAME within this
|        scope, never tenant-wide -- the same name exists in other environments (measured 2026-10-01: three endpoints
|        named dce-securityinsight in two subscriptions).
|          Subscription  -SubscriptionId, else -WorkspaceResourceId's, else SI_AzSubscriptionId, else SI_WorkspaceResourceId's,
|                        else the 2.2.x SubscriptionId (a new rule is created in the workspace's subscription, as the
|                        module did; SI_AzSubscriptionId is filled from the workspace by Initialize-SIIngestGlobals)
|          DcrRg         -DcrResourceGroup, else SI_DcrResourceGroup
|          DceRg         -DceResourceGroup, else SI_DceResourceGroup, else the DCR resource group
|    #>
|    param([string]$SubscriptionId, [string]$WorkspaceResourceId, [string]$DcrResourceGroup, [string]$DceResourceGroup)
|    $sub = $SubscriptionId
|    if (-not $sub -and $WorkspaceResourceId -match '/subscriptions/([^/]+)/') { $sub = $Matches[1] }
|    if (-not $sub) { $sub = [string]$global:SI_AzSubscriptionId }
|    if (-not $sub -and "$($global:SI_WorkspaceResourceId)" -match '/subscriptions/([^/]+)/') { $sub = $Matches[1] }
|    if (-not $sub) { $sub = [string]$global:SubscriptionId }
|    $dcrRg = if ($DcrResourceGroup) { $DcrResourceGroup } else { [string]$global:SI_DcrResourceGroup }
|    $dceRg = if ($DceResourceGroup) { $DceResourceGroup } elseif ($global:SI_DceResourceGroup) { [string]$global:SI_DceResourceGroup } else { $dcrRg }
|    [pscustomobject]@{ Subscription = $sub; DcrRg = $dcrRg; DceRg = $dceRg }
|}
|
|function Get-SILogScopedList {
|    param([ValidateSet('Dce', 'Dcr')][string]$Kind, [string]$SubscriptionId, [string]$ResourceGroup, [hashtable]$Auth)
|    if ([string]::IsNullOrWhiteSpace($SubscriptionId)) {
|        throw ("No subscription is configured for the data collection {0} lookup (SI_AzSubscriptionId / SI_WorkspaceResourceId). It is never read tenant-wide, because the same name exists in other environments." -f $(if ($Kind -eq 'Dce') { 'endpoint' } else { 'rule' }))
|    }
|    $type = if ($Kind -eq 'Dce') { 'dataCollectionEndpoints' } else { 'dataCollectionRules' }
|    $path = if ($ResourceGroup) { "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.Insights/$type" }
|            else { "/subscriptions/$SubscriptionId/providers/Microsoft.Insights/$type" }
|    return (Get-SILogArmList -Path $path -ApiVersion (Get-SILogArmApiVersion $Kind) -Auth $Auth)
|}
|
|function Get-SIDceListRest {
|    <# REST twin of Get-AzDceListAll -- but SCOPED: the configured subscription only (never tenant-wide). Same auth
|       arguments as the module; -SubscriptionId / -ResourceGroup narrow further. #>
|    [CmdletBinding()]
|    param([string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId, [string]$SubscriptionId, [string]$ResourceGroup)
|    $auth = Resolve-SILogIngestAuth -Bound $PSBoundParameters
|    $scope = Get-SILogIngestScope -SubscriptionId $SubscriptionId
|    return (Get-SILogScopedList -Kind Dce -SubscriptionId $scope.Subscription -ResourceGroup $ResourceGroup -Auth $auth)
|}
|
|function Get-SIDcrListRest {
|    <# REST twin of Get-AzDcrListAll -- scoped to the configured subscription, like Get-SIDceListRest. #>
|    [CmdletBinding()]
|    param([string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId, [string]$SubscriptionId, [string]$ResourceGroup)
|    $auth = Resolve-SILogIngestAuth -Bound $PSBoundParameters
|    $scope = Get-SILogIngestScope -SubscriptionId $SubscriptionId
|    return (Get-SILogScopedList -Kind Dcr -SubscriptionId $scope.Subscription -ResourceGroup $ResourceGroup -Auth $auth)
|}
|
|function Find-SILogResourceByName {
|    <#
|        A DCR or DCE by NAME in the configured scope:
|          resource group known  -> exactly that resource (GET by its id); nothing else is considered
|          resource group absent -> the subscription's list; one match is used, several refuse (the name is ambiguous)
|        -AnyResourceGroupWhenMissing (endpoints only): not in the resource group, but exactly ONE of that name in the
|        subscription -> that one (an endpoint outside the rules' resource group has always worked); several refuse.
|        Returns $null when there is none.
|    #>
|    param([ValidateSet('Dce', 'Dcr')][string]$Kind, [Parameter(Mandatory)][string]$Name, [string]$SubscriptionId, [string]$ResourceGroup, [hashtable]$Auth, [switch]$AnyResourceGroupWhenMissing)
|    $label = if ($Kind -eq 'Dce') { 'data collection endpoint' } else { 'data collection rule' }
|    if ([string]::IsNullOrWhiteSpace($SubscriptionId)) { throw ("No subscription is configured to look up {0} '{1}' in (SI_AzSubscriptionId / SI_WorkspaceResourceId)." -f $label, $Name) }
|    $type = if ($Kind -eq 'Dce') { 'dataCollectionEndpoints' } else { 'dataCollectionRules' }
|    if ($ResourceGroup) {
|        $hit = Invoke-SILogArm -Path "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.Insights/$type/$Name" -ApiVersion (Get-SILogArmApiVersion $Kind) -Auth $Auth -AllowNotFound
|        if ($hit -or -not $AnyResourceGroupWhenMissing) { return $hit }
|    }
|    $same = @(Get-SILogScopedList -Kind $Kind -SubscriptionId $SubscriptionId -Auth $Auth | Where-Object { $_ -and $_.name -eq $Name })
|    if ($same.Count -eq 1) { return $same[0] }
|    if ($same.Count -gt 1) {
|        throw ("{0} '{1}' exists {2} times in subscription '{3}'{4}, so nothing was posted -- set the resource group this install uses ({5})." -f `
|            $label, $Name, $same.Count, $SubscriptionId, $(if ($ResourceGroup) { " (none in resource group '$ResourceGroup')" } else { '' }),
|            $(if ($Kind -eq 'Dce') { 'SI_DceResourceGroup' } else { 'SI_DcrResourceGroup' }))
|    }
|    return $null
|}
|
|# =====================================================================================================================
|#  REST: data shape -- exact twins of the module's pre-processing (so 'Rest' declares and posts the same columns)
|# =====================================================================================================================
|
|function Add-SICollectionTimeRest {
|    <#
|        CollectionTime on every row, IDENTICAL across all shards and batches of one run:
|          * a row that already carries a CollectionTime keeps it -- the engines stamp the run's own value upstream
|            ($RunContext.CollectionTime / $global:RA_CollectionTime), and that is the value every shard shares;
|          * a row without one gets this process's run value, minted once and reused by every later call.
|        Same value format as the module ([datetime] from "yyyy-MM-ddTHH:mm:ssK", UTC).
|        DIFFERS FROM THE MODULE ON PURPOSE: Add-CollectionTimeToAllEntriesInArray overwrites every row with the time
|        of THAT call, so a "safety net" call after the upstream stamp replaced the shared run value.
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data)
|    if (-not ($global:SI_LogIngestRunCollectionTime -is [datetime])) {
|        [datetime]$ct = (Get-Date ([datetime]::Now.ToUniversalTime()) -Format 'yyyy-MM-ddTHH:mm:ssK')
|        $global:SI_LogIngestRunCollectionTime = $ct
|    }
|    $out = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($e in $Data) {
|        $p = $e.PSObject.Properties['CollectionTime']
|        if (-not $p -or $null -eq $p.Value -or [string]::IsNullOrWhiteSpace([string]$p.Value)) {
|            $e | Add-Member -MemberType NoteProperty -Name CollectionTime -Value $global:SI_LogIngestRunCollectionTime -Force | Out-Null
|        }
|        [void]$out.Add($e)
|    }
|    return [array]$out.ToArray()
|}
|
|function Add-SIColumnDataRest {
|    <# Twin of Add-ColumnDataToAllEntriesInArray: up to three columns with one value each, on every row. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data, [Parameter(Mandatory)][string]$Column1Name, [Parameter(Mandatory)][AllowEmptyString()][string]$Column1Data,
|          [string]$Column2Name, [string]$Column2Data, [string]$Column3Name, [string]$Column3Data)
|    $out = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($e in $Data) {
|        if ($Column1Name) { $e | Add-Member -MemberType NoteProperty -Name $Column1Name -Value $Column1Data -Force }
|        if ($Column2Name) { $e | Add-Member -MemberType NoteProperty -Name $Column2Name -Value $Column2Data -Force }
|        if ($Column3Name) { $e | Add-Member -MemberType NoteProperty -Name $Column3Name -Value $Column3Data -Force }
|        [void]$out.Add($e)
|    }
|    return [array]$out.ToArray()
|}
|
|function Repair-SILogColumnNameRest {
|    <# Twin of ValidateFix-AzLogAnalyticsTableSchemaColumnNames (1.7.x): prohibited names get '_', ':' '-' '.' are
|       removed, leading '_' trimmed, leading whitespace trimmed, >45 characters cut; renamed columns move to the end
|       of the row with their own values. Rows are rebuilt only when a name needs fixing. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data)
|    $prohibited = @('_ResourceId', 'id', '_ResourceId', '_SubscriptionId', 'TenantId', 'Type', 'UniqueId', 'Title', 'Date')
|    $checked = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    $rename = @{}
|    foreach ($e in $Data) {
|        foreach ($p in $e.PSObject.Properties) {
|            $n = $p.Name
|            if (-not $checked.Add($n)) { continue }
|            if ($n -in $prohibited)     { $rename[$n] = $n + '_' }
|            elseif ($n -like '*:*')     { $rename[$n] = $n.Replace(':', '') }
|            elseif ($n -like '*-*')     { $rename[$n] = $n.Replace('-', '') }
|            elseif ($n -like '*.*')     { $rename[$n] = $n.Replace('.', '') }
|            elseif ($n -like '_*')      { $rename[$n] = $n.TrimStart('_') }
|            elseif ($n -like '* *')     { $rename[$n] = $n.TrimStart() }
|            elseif ($n.Length -gt 45)   { $rename[$n] = $n.Substring(0, 45) }
|        }
|    }
|    if ($rename.Count -eq 0) { return [array]$Data }
|    # #639: only a row that CARRIES a name to fix is rebuilt (a copy of that row); every other row is passed on as it is --
|    # never a copy of the whole post. (Not in place: the caller may still read the row by its own names.)
|    $out = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($row in $Data) {
|        $needs = $false
|        foreach ($p in $row.PSObject.Properties) { if ($rename.ContainsKey($p.Name)) { $needs = $true; break } }
|        if (-not $needs) { [void]$out.Add($row); continue }
|        $rebuilt = [ordered]@{}
|        $moved = New-Object 'System.Collections.Generic.List[object]'
|        foreach ($p in $row.PSObject.Properties) {
|            if ($rename.ContainsKey($p.Name)) { [void]$moved.Add($p) } else { $rebuilt[$p.Name] = $p.Value }
|        }
|        foreach ($p in $moved) { $rebuilt[[string]$rename[$p.Name]] = $p.Value }
|        [void]$out.Add([pscustomobject]$rebuilt)
|    }
|    return [array]$out.ToArray()
|}
|
|function Get-SILogSchemaRest {
|    <#
|        Twin of Get-ObjectSchemaAsArray (-As Array) and Get-ObjectSchemaAsHash (-As Hash): the column list of the
|        WHOLE set, each column's type from the first row that carries it, read the way the module reads it -- the row
|        is round-tripped through JSON and the type taken from Get-Member's definition:
|            int* / real* -> int    long* -> long    guid* -> dynamic    string* -> string    datetime* -> datetime
|            bool* -> boolean       object* / PSCustomObject -> dynamic
|        DIFFERENCES FROM THE MODULE (2026-10-11, both made Log Analytics discard values):
|          * a fractional number is `real` -- the module matched none of its patterns and INHERITED the type of the column
|            read just before it (alphabetically), which is how LastSignInDays became datetime;
|          * an empty (null) value does not decide the type: the first row with a value does, 'dynamic' if none has one.
|        KNOWN TRAP KEPT:
|          * 'int' vs 'long' follows the value's size in the first row that has the column.
|        -ReturnType Table adds TimeGenerated (datetime) first and a description per column; DCR (the default for Array)
|        has name + type only. -As Hash returns hashtables and, like the module, nothing without -ReturnType.
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data, [ValidateSet('Array', 'Hash')][string]$As = 'Array', [ValidateSet('Table', 'DCR')][string[]]$ReturnType)
|    $table = New-Object 'System.Collections.Generic.List[object]'
|    $dcr   = New-Object 'System.Collections.Generic.List[object]'
|    $seen  = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    [void]$seen.Add('TimeGenerated')
|    # the module's shapes: Array -> PSCustomObject, Hash -> plain hashtable
|    $mk = { param($n, $t, [switch]$Desc)
|        if ($As -eq 'Hash') { if ($Desc) { @{ name = $n; type = $t; description = '' } } else { @{ name = $n; type = $t } } }
|        elseif ($Desc) { [pscustomobject]@{ name = $n; type = $t; description = '' } }
|        else { [pscustomobject]@{ name = $n; type = $t } }
|    }
|    [void]$table.Add((& $mk 'TimeGenerated' 'datetime' -Desc))
|    # columns seen so far only EMPTY (null): typed from the first row that has a value, 'dynamic' when none has
|    $nullOnly = New-Object 'System.Collections.Generic.List[string]'
|    $nullSet  = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    foreach ($entry in $Data) {
|        $hasNew = $false
|        foreach ($p in $entry.PSObject.Properties) { if (-not $seen.Contains($p.Name) -and ($null -ne $p.Value -or -not $nullSet.Contains($p.Name))) { $hasNew = $true; break } }
|        if (-not $hasNew) { continue }
|        $cols = $entry | ConvertTo-Json -Depth 100 | ConvertFrom-Json | Get-Member -MemberType NoteProperty
|        foreach ($c in $cols) {
|            if ($seen.Contains($c.Name)) { continue }
|            $d = [string]$c.Definition
|            # ring 1, 2026-10-11 -- THE TYPE IS DECIDED PER COLUMN, NEVER INHERITED. The module's mapping kept the previous
|            # column's type for a definition it did not know (a double), and Get-Member lists the columns alphabetically,
|            # so LastSignInDays (a double) was declared after LastSignInDateTime: datetime -- and every value of it was then
|            # discarded by Log Analytics. A fractional number is `real`; an empty value waits for a row that has one.
|            $objType = $null
|            if ($d -match '^(?i)(System\.)?Object\s') {   # a null value round-trips as "object <name>=null"
|                if ($nullSet.Add($c.Name)) { [void]$nullOnly.Add($c.Name) }
|                continue
|            }
|            if     ($d -like 'int*')      { $objType = 'int' }
|            elseif ($d -like 'real*')     { $objType = 'int' }
|            elseif ($d -like 'long*')     { $objType = 'long' }
|            elseif ($d -like 'double*' -or $d -like 'decimal*' -or $d -like 'float*' -or $d -like 'single*') { $objType = 'real' }
|            elseif ($d -like 'guid*')     { $objType = 'dynamic' }
|            elseif ($d -like 'string*')   { $objType = 'string' }
|            elseif ($d -like 'datetime*') { $objType = 'datetime' }
|            elseif ($d -like 'bool*')     { $objType = 'boolean' }
|            elseif ($d -like 'object*')   { $objType = 'dynamic' }
|            elseif ($d -like 'System.Management.Automation.PSCustomObject*') { $objType = 'dynamic' }
|            else { $objType = 'dynamic' }
|            [void]$seen.Add($c.Name)
|            [void]$table.Add((& $mk $c.Name $objType -Desc))
|            [void]$dcr.Add((& $mk $c.Name $objType))
|        }
|    }
|    foreach ($n in $nullOnly) {
|        if ($seen.Contains($n)) { continue }
|        [void]$seen.Add($n)
|        [void]$table.Add((& $mk $n 'dynamic' -Desc))
|        [void]$dcr.Add((& $mk $n 'dynamic'))
|    }
|    if ($ReturnType -eq 'Table') { return $table.ToArray() }
|    if ($ReturnType -eq 'DCR' -or $As -eq 'Array') { return $dcr.ToArray() }
|}
|
|function Format-SILogRowsToSchemaRest {
|    <# Twin of Build-DataArrayToAlignWithSchema (1.7.x): every row gets every schema column (missing = $null), in
|       schema order; a property the schema does not list (a literal TimeGenerated) is kept, after them.
|       #639: IN PLACE, never a padded copy of the whole post. A PSCustomObject row is aligned on itself (its properties
|       re-ordered, the missing ones added as $null) -- the same row, the same JSON as the copy made before; a row of another
|       kind (a hashtable, a compact .NET row) is replaced in the array by its aligned copy, one row at a time. The post
|       then serialises a batch at a time (Send-SILogDataRest), so nothing of the post is ever held twice. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data)
|    $schema = Get-SILogSchemaRest -Data $Data -As Array
|    if (@($Data).Count -eq 0) { return $Data }
|    $names = New-Object 'System.Collections.Generic.List[string]'
|    foreach ($c in $schema) { [void]$names.Add([string]$c.name) }
|    $nm = $names.ToArray()
|    for ($i = 0; $i -lt $Data.Count; $i++) { $Data[$i] = Format-SILogRowToNamesInPlace -Row $Data[$i] -Names $nm }
|    return $Data
|}
|
|function Format-SILogRowToNamesInPlace {
|    <# ONE row aligned to -Names (missing = $null, in that order, the other properties after them) -- the row itself when
|       it is a PSCustomObject (its properties re-ordered in place; nothing done when it already is aligned), else its
|       aligned copy (Format-SILogRowsToNames). The JSON of the result equals the JSON of Format-SILogRowsToNames. #>
|    param($Row, [Parameter(Mandatory)][AllowEmptyCollection()][string[]]$Names)
|    if ($null -eq $Row) { return $Row }
|    if ($Row.PSObject.BaseObject -isnot [System.Management.Automation.PSCustomObject]) {
|        return @(Format-SILogRowsToNames -Data @($Row) -Names $Names)[0]
|    }
|    $props = $Row.PSObject.Properties
|    # already aligned: the names first, in order, every one present -- nothing to do
|    $all = @($props)
|    $aligned = ($all.Count -ge $Names.Count)
|    if ($aligned) { for ($k = 0; $k -lt $Names.Count; $k++) { if ($all[$k].Name -cne $Names[$k] -or $all[$k] -isnot [System.Management.Automation.PSNoteProperty]) { $aligned = $false; break } } }
|    if ($aligned) { return $Row }
|    foreach ($p in $all) { if ($p -isnot [System.Management.Automation.PSNoteProperty]) { return @(Format-SILogRowsToNames -Data @($Row) -Names $Names)[0] } }
|    $set = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
|    foreach ($n in $Names) { [void]$set.Add($n) }
|    # the values, then the properties rebuilt on the same object: the names in order, then the others as they were
|    $vals = @{}
|    $rest = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($p in $all) {
|        if ($set.Contains($p.Name)) { if (-not $vals.ContainsKey($p.Name)) { $vals[$p.Name] = $p } }
|        else { $rest.Add($p) }
|    }
|    foreach ($p in $all) { $props.Remove($p.Name) }
|    foreach ($n in $Names) {
|        $v = $null; if ($vals.ContainsKey($n)) { $v = $vals[$n].Value }
|        $props.Add([System.Management.Automation.PSNoteProperty]::new($n, $v))
|    }
|    foreach ($p in $rest) { $props.Add([System.Management.Automation.PSNoteProperty]::new($p.Name, $p.Value)) }
|    return $Row
|}
|
|function Format-SILogRowsToNames {
|    <# PURE. Format-SILogRowsToSchemaRest's second half: every row gets every column of -Names (missing = $null), in that
|       order; a property not in -Names is kept, after them. Each row on its own -- the names are the whole set's schema, read
|       before (Risk Analysis prepares the rows of one chunk on several cores with it, #744). #>
|    param([Parameter(Mandatory)][AllowEmptyCollection()][Array]$Data, [Parameter(Mandatory)][AllowEmptyCollection()][string[]]$Names)
|    $out = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($row in $Data) {
|        $props = $row.PSObject.Properties
|        $a = [ordered]@{}
|        foreach ($n in $Names) { $p = $props[$n]; if ($null -ne $p) { $a[$n] = $p.Value } else { $a[$n] = $null } }
|        foreach ($p in $props) { if (-not $a.Contains($p.Name)) { $a[$p.Name] = $p.Value } }
|        [void]$out.Add([pscustomobject]$a)
|    }
|    return $out.ToArray()
|}
|
|# =====================================================================================================================
|#  REST: table + DCR create / update -- ADDITIVE only
|# =====================================================================================================================
|
|function Get-SILogStreamName {
|    <# 'Custom-<table>_CL', cut to 52 characters (the stream name limit) -- the module's rule. #>
|    param([Parameter(Mandatory)][string]$TableName)
|    $s = 'Custom-' + $TableName + '_CL'
|    if ($s.Length -gt 52) { $s = $s.Substring(0, 52) }
|    return $s
|}
|
|function Get-SILogTableRest {
|    param([Parameter(Mandatory)][string]$WorkspaceResourceId, [Parameter(Mandatory)][string]$TableName, [hashtable]$Auth, [switch]$NoCache)
|    return (Invoke-SILogArm -Path ($WorkspaceResourceId + '/tables/' + $TableName + '_CL') -ApiVersion (Get-SILogArmApiVersion Table) -Auth $Auth -AllowNotFound -NoCache:$NoCache)
|}
|
|function Resolve-SILogDcrForTable {
|    <# The rule this install posts through: the one recorded this run when it was created/updated, else by name in the
|       configured scope (Find-SILogResourceByName). #>
|    param([Parameter(Mandatory)][string]$DcrName, [string]$SubscriptionId, [string]$ResourceGroup, [hashtable]$Auth)
|    $ids = (Get-SILogIngestRunCache).DcrIds
|    $key = $DcrName.ToLowerInvariant()   # the rule created / updated / found THIS run, wherever the caller put it
|    if ($ids.ContainsKey($key)) {
|        $hit = Invoke-SILogArm -Path $ids[$key] -ApiVersion (Get-SILogArmApiVersion Dcr) -Auth $Auth -AllowNotFound
|        if ($hit) { return $hit }
|    }
|    return (Find-SILogResourceByName -Kind Dcr -Name $DcrName -SubscriptionId $SubscriptionId -ResourceGroup $ResourceGroup -Auth $Auth)
|}
|
|function Test-SILogTableDcrStatusRest {
|    <# Twin of Get-AzLogAnalyticsTableAzDataCollectionRuleStatus: $true when the table or the rule must be created or
|       given columns. The rule is looked up in the configured scope, not by name across the tenant. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$AzLogWorkspaceResourceId, [Parameter(Mandatory)][string]$TableName, [Parameter(Mandatory)][string]$DcrName,
|          [Parameter(Mandatory)][array]$SchemaSourceObject, [string]$DcrResourceGroup,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    $auth = Resolve-SILogIngestAuth -Bound $PSBoundParameters
|    $scope = Get-SILogIngestScope -WorkspaceResourceId $AzLogWorkspaceResourceId -DcrResourceGroup $DcrResourceGroup
|    $needs = $false
|    $t = Get-SILogTableRest -WorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -Auth $auth -NoCache
|    $cols = @(); $std = @()
|    if (-not $t) { $needs = $true }
|    else {
|        $cols = @($t.properties.schema.columns); $std = @($t.properties.schema.standardColumns)
|        foreach ($e in $SchemaSourceObject) {
|            if (-not ($cols | Where-Object { $_.name -eq $e.name }) -and -not ($std | Where-Object { $_.name -eq $e.name })) { $needs = $true }
|        }
|    }
|    $dcr = Resolve-SILogDcrForTable -DcrName $DcrName -SubscriptionId $scope.Subscription -ResourceGroup $scope.DcrRg -Auth $auth
|    if (-not $dcr) { return $true }
|    (Get-SILogIngestRunCache).DcrIds[$DcrName.ToLowerInvariant()] = [string]$dcr.id   # the post uses THIS rule
|    $stream = Get-SILogStreamName -TableName $TableName
|    $dcrCols = @()
|    if ($dcr.properties.streamDeclarations -and $dcr.properties.streamDeclarations.PSObject.Properties[$stream]) { $dcrCols = @($dcr.properties.streamDeclarations.$stream.columns) }
|    $tableCols = @($cols | Where-Object { $_.name -ne 'TimeGenerated' })
|    if ($dcrCols.Count -lt $tableCols.Count) { return $true }
|    foreach ($c in $tableCols) { if (-not ($dcrCols | Where-Object { $_.name -eq $c.name })) { $needs = $true } }
|    return $needs
|}
|
|function Set-SILogTableRest {
|    <#
|        Twin of CreateUpdate-AzLogAnalyticsCustomLogTableDcr, ADDITIVE ONLY:
|          no table   -> PUT it with the schema of the data (TimeGenerated + every column)
|          table      -> the columns it does not have yet are added (PATCH: retention and plan are left as they are); an
|                        existing column is never changed or removed, whatever type the data now suggests
|        A refused write FAILS with Azure's answer. The module's fallback -- DELETE the table and re-create it -- is not
|        copied: it discards data.
|        -SchemaSourceObject: the Table-format schema (Get-SILogSchemaRest -ReturnType Table / Get-ObjectSchemaAsHash).
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$TableName, [Parameter(Mandatory)][array]$SchemaSourceObject, [Parameter(Mandatory)][string]$AzLogWorkspaceResourceId,
|          [string]$SchemaMode = 'Merge',
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    $auth = Resolve-SILogIngestAuth -Bound $PSBoundParameters
|    $table = $TableName + '_CL'
|    if ($table.Length -gt 45) { Write-Error ("ERROR - Reduce length of tablename, as it has a maximum of 45 characters (current length: {0})" -f $table.Length) }
|    $path = $AzLogWorkspaceResourceId + '/tables/' + $table
|    $cur = Get-SILogTableRest -WorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -Auth $auth -NoCache
|    $toCol = { param($c) [ordered]@{ name = [string]$c.name; type = [string]$c.type; description = '' } }
|    if (-not $cur) {
|        $columns = @($SchemaSourceObject | ForEach-Object { & $toCol $_ })
|        $null = Invoke-SILogArm -Method PUT -Path $path -ApiVersion (Get-SILogArmApiVersion Table) -Auth $auth -Body @{ properties = @{ schema = @{ name = $table; columns = $columns } } }
|        Write-Output ("table {0}: created with {1} column(s)" -f $table, $columns.Count)
|        return
|    }
|    $std = @($cur.properties.schema.standardColumns | ForEach-Object { [string]$_.name })
|    $merged = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($c in @($cur.properties.schema.columns)) { if ($c -and ([string]$c.name -notin $std)) { [void]$merged.Add((& $toCol $c)) } }
|    $added = New-Object 'System.Collections.Generic.List[string]'
|    foreach ($s in $SchemaSourceObject) {
|        if ([string]$s.name -in $std) { continue }
|        if (@($merged | Where-Object { $_.name -eq [string]$s.name }).Count) { continue }
|        [void]$merged.Add((& $toCol $s)); [void]$added.Add([string]$s.name)
|    }
|    if ($added.Count -eq 0) { Write-Output ("table {0}: has every column" -f $table); return }
|    $null = Invoke-SILogArm -Method PATCH -Path $path -ApiVersion (Get-SILogArmApiVersion Table) -Auth $auth -Body @{ properties = @{ schema = @{ name = $table; columns = @($merged.ToArray()) } } }
|    Write-Output ("table {0}: {1} column(s) added ({2})" -f $table, $added.Count, ($added -join ', '))
|}
|
|function Resolve-SILogEndpointForNewRule {
|    <# This install's endpoint, for a NEW rule: by name in SI_DceResourceGroup (else the rules' group) of the
|       subscription; one of that name elsewhere in the subscription is unambiguous; several refuse. #>
|    param([Parameter(Mandatory)][string]$DceName, $Scope, [hashtable]$Auth)
|    $dce = Find-SILogResourceByName -Kind Dce -Name $DceName -SubscriptionId $Scope.Subscription -ResourceGroup $Scope.DceRg -Auth $Auth -AnyResourceGroupWhenMissing
|    if (-not $dce) {
|        throw ("Data collection endpoint '{0}' was not found in resource group '{1}' of subscription '{2}', so nothing was created or posted." -f $DceName, $Scope.DceRg, $Scope.Subscription)
|    }
|    return $dce
|}
|
|function Set-SILogDcrRest {
|    <#
|        Twin of CreateUpdate-AzDataCollectionRuleLogIngestCustomLog, ADDITIVE ONLY:
|          no rule -> PUT one in the configured subscription + resource group, bound to THIS install's endpoint, with the
|                     stream declaration (the data's columns), the workspace destination and the default transform
|          rule    -> the columns the table has and the stream does not are ADDED to the stream declaration; everything
|                     else the rule carries (its endpoint, transform, destinations, other streams) is kept as it is. The
|                     module rebuilt the whole rule instead, re-binding it to the endpoint it found by name (#198).
|        A new rule waits 15 seconds for Azure to settle, as the module did.
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][array]$SchemaSourceObject, [Parameter(Mandatory)][string]$AzLogWorkspaceResourceId, [string]$DceName,
|          [Parameter(Mandatory)][string]$DcrResourceGroup, [Parameter(Mandatory)][string]$DcrName, [Parameter(Mandatory)][string]$TableName,
|          [boolean]$AzDcrSetLogIngestApiAppPermissionsDcrLevel = $false, [AllowEmptyString()][string]$LogIngestServicePricipleObjectId, [string]$SchemaMode = 'Merge',
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    $auth = Resolve-SILogIngestAuth -Bound $PSBoundParameters
|    $scope = Get-SILogIngestScope -WorkspaceResourceId $AzLogWorkspaceResourceId -DcrResourceGroup $DcrResourceGroup
|    $stream = Get-SILogStreamName -TableName $TableName
|    $wsName = ($AzLogWorkspaceResourceId -split '/')[-1]
|    $dcrPath = "/subscriptions/$($scope.Subscription)/resourceGroups/$DcrResourceGroup/providers/Microsoft.Insights/dataCollectionRules/$DcrName"
|    $ids = (Get-SILogIngestRunCache).DcrIds
|    $key = $DcrName.ToLowerInvariant()
|    $dcr = Invoke-SILogArm -Path $dcrPath -ApiVersion (Get-SILogArmApiVersion Dcr) -Auth $auth -AllowNotFound -NoCache
|    $toCol = { param($c) [ordered]@{ name = [string]$c.name; type = [string]$c.type } }
|
|    if (-not $dcr) {
|        $dce = Resolve-SILogEndpointForNewRule -DceName $DceName -Scope $scope -Auth $auth
|        # #294: a new rule for a table that EXISTS declares the table's columns with the TABLE's types (then any column of
|        # the data the table does not have yet). Declared from the data instead, a type that differs from the table's
|        # (a column the data reads as an object, the table holds as text) makes Azure refuse the rule.
|        $tNew = Get-SILogTableRest -WorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -Auth $auth -NoCache
|        $cols = @(Get-SILogNewRuleColumns -Table $tNew -SchemaSourceObject $SchemaSourceObject)
|        $body = [ordered]@{
|            location   = [string]$dce.location
|            properties = [ordered]@{
|                dataCollectionEndpointId = [string]$dce.id
|                streamDeclarations       = @{ $stream = @{ columns = $cols } }
|                destinations             = @{ logAnalytics = @(@{ workspaceResourceId = $AzLogWorkspaceResourceId; name = $wsName }) }
|                dataFlows                = @(@{ streams = @($stream); destinations = @($wsName); transformKql = 'source | extend TimeGenerated = now()'; outputStream = $stream })
|            }
|        }
|        $created = Invoke-SILogArm -Method PUT -Path $dcrPath -ApiVersion (Get-SILogArmApiVersion Dcr) -Auth $auth -Body $body
|        $ids[$key] = $dcrPath
|        Write-Output ("data collection rule {0}: created on endpoint {1} with {2} column(s)" -f $DcrName, $dce.id, $cols.Count)
|        if ($AzDcrSetLogIngestApiAppPermissionsDcrLevel -and $LogIngestServicePricipleObjectId) {
|            $roleDef = "/subscriptions/$($scope.Subscription)/providers/Microsoft.Authorization/roleDefinitions/3913510d-42f4-4e42-8a64-420c390055eb"
|            try {
|                $null = Invoke-SILogArm -Method PUT -Path ($dcrPath + '/providers/Microsoft.Authorization/roleAssignments/' + [guid]::NewGuid().ToString()) -ApiVersion (Get-SILogArmApiVersion Role) -Auth $auth `
|                    -Body @{ properties = @{ roleDefinitionId = $roleDef; principalId = $LogIngestServicePricipleObjectId; principalType = 'ServicePrincipal' } }
|            } catch { Write-Warning ("Monitoring Metrics Publisher on {0} was not granted: {1}" -f $DcrName, $_.Exception.Message) }
|        }
|        Start-Sleep -Seconds 15
|        return
|    }
|
|    $ids[$key] = [string]$dcr.id
|    # the columns the stream must carry: the table's (after Set-SILogTableRest), plus Computer/RawData when they are
|    # standard columns of a table migrated from v1 -- the module's rule
|    $t = Get-SILogTableRest -WorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -Auth $auth -NoCache
|    $want = New-Object 'System.Collections.Generic.List[object]'
|    if ($t) {
|        foreach ($c in @($t.properties.schema.columns)) { if ($c -and $c.name -ne 'TimeGenerated') { [void]$want.Add((& $toCol $c)) } }
|        foreach ($n in 'Computer', 'RawData') {
|            if (-not @($want | Where-Object { $_.name -eq $n }).Count -and @($t.properties.schema.standardColumns | Where-Object { $_.name -eq $n }).Count) { [void]$want.Add([ordered]@{ name = $n; type = 'string' }) }
|        }
|    } else {
|        foreach ($c in $SchemaSourceObject) { if ($c.name -ne 'TimeGenerated') { [void]$want.Add((& $toCol $c)) } }
|    }
|    $p = $dcr.properties
|    if (-not $p.streamDeclarations) { $p | Add-Member -NotePropertyName streamDeclarations -NotePropertyValue ([pscustomobject]@{}) -Force }
|    $hasStream = [bool]$p.streamDeclarations.PSObject.Properties[$stream]
|    $have = if ($hasStream) { @($p.streamDeclarations.$stream.columns) } else { @() }
|    $merged = New-Object 'System.Collections.Generic.List[object]'
|    foreach ($c in $have) { if ($c) { [void]$merged.Add((& $toCol $c)) } }
|    $added = New-Object 'System.Collections.Generic.List[string]'
|    foreach ($c in $want) { if (-not @($merged | Where-Object { $_.name -eq $c.name }).Count) { [void]$merged.Add($c); [void]$added.Add([string]$c.name) } }
|    if ($added.Count -eq 0) { Write-Output ("data collection rule {0}: has every column" -f $DcrName); return }
|
|    if ($hasStream) { $p.streamDeclarations.$stream.columns = @($merged.ToArray()) }
|    else {
|        $p.streamDeclarations | Add-Member -NotePropertyName $stream -NotePropertyValue ([pscustomobject]@{ columns = @($merged.ToArray()) })
|        $flows = @($p.dataFlows)
|        if (-not @($flows | Where-Object { @($_.streams) -contains $stream }).Count) {
|            $dest = @($p.destinations.logAnalytics)[0]
|            $p.dataFlows = @($flows) + @([pscustomobject]@{ streams = @($stream); destinations = @([string]$dest.name); transformKql = 'source | extend TimeGenerated = now()'; outputStream = $stream })
|        }
|    }
|    $props = [ordered]@{}
|    foreach ($q in $p.PSObject.Properties) { if ($q.Name -notin 'immutableId', 'provisioningState', 'endpoints', 'metadata') { $props[$q.Name] = $q.Value } }
|    $body = [ordered]@{ location = [string]$dcr.location; properties = $props }
|    if ($dcr.PSObject.Properties['kind'] -and $dcr.kind) { $body['kind'] = $dcr.kind }
|    if ($dcr.PSObject.Properties['tags'] -and $dcr.tags) { $body['tags'] = $dcr.tags }
|    $null = Invoke-SILogArm -Method PUT -Path ([string]$dcr.id) -ApiVersion (Get-SILogArmApiVersion Dcr) -Auth $auth -Body $body
|    Write-Output ("data collection rule {0}: {1} column(s) added to {2} ({3})" -f $DcrName, $added.Count, $stream, ($added -join ', '))
|}
|
|function Update-SILogTableSchemaRest {
|    <#
|        Twin of CheckCreateUpdate-TableDcr-Structure: the table and the rule carry every column of the data (the WHOLE
|        set decides the schema). Same arguments as the module. Additive only (Set-SILogTableRest / Set-SILogDcrRest).
|        A table name with '_' first, '-', ':', '.' or a space is refused as the module refuses it (nothing is done).
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][Array]$Data, [Parameter(Mandatory)][string]$AzLogWorkspaceResourceId, [Parameter(Mandatory)][string]$TableName,
|          [Parameter(Mandatory)][string]$DcrName, [string]$DcrResourceGroup, [string]$DceName,
|          [AllowEmptyString()][AllowEmptyCollection()][string]$LogIngestServicePricipleObjectId, [boolean]$AzDcrSetLogIngestApiAppPermissionsDcrLevel = $false,
|          [boolean]$AzLogDcrTableCreateFromAnyMachine, [string]$SchemaMode = 'Merge', [boolean]$EnableUploadViaLogHub = $false,
|          [AllowEmptyCollection()][array]$AzLogDcrTableCreateFromReferenceMachine,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine',
|          [switch]$UseManagedIdentity, [string]$ManagedIdentityClientId, [string]$TenantId)
|    if ($TableName -like '_*' -or $TableName -like '*-*' -or $TableName -like '*:*' -or $TableName -like '*.*' -or $TableName -like '* *') {
|        Write-Verbose ("ISSUE - Table name [ {0} ] is not a valid Log Analytics table name" -f $TableName)
|        return
|    }
|    if ($EnableUploadViaLogHub) { return }
|    if (-not ($AzLogDcrTableCreateFromAnyMachine -or ($env:COMPUTERNAME -and $env:COMPUTERNAME -in @($AzLogDcrTableCreateFromReferenceMachine)))) { return }
|    if (-not $DcrResourceGroup) { $DcrResourceGroup = (Get-SILogIngestScope -WorkspaceResourceId $AzLogWorkspaceResourceId).DcrRg }
|    $authArgs = @{}
|    foreach ($k in 'AzAppId', 'AzAppSecret', 'AzAppCertificateThumbprint', 'AzAppCertificateStoreLocation', 'UseManagedIdentity', 'ManagedIdentityClientId', 'TenantId') {
|        if ($PSBoundParameters.ContainsKey($k)) { $authArgs[$k] = $PSBoundParameters[$k] }
|    }
|    $schema = Get-SILogSchemaRest -Data $Data -As Array
|    $needs = Test-SILogTableDcrStatusRest -AzLogWorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -DcrName $DcrName -SchemaSourceObject $schema -DcrResourceGroup $DcrResourceGroup @authArgs
|    if (-not $needs) { Write-Output ("table {0}_CL and rule {1}: every column is declared" -f $TableName, $DcrName); return }
|    Set-SILogTableRest -AzLogWorkspaceResourceId $AzLogWorkspaceResourceId -TableName $TableName -SchemaSourceObject (Get-SILogSchemaRest -Data $Data -As Hash -ReturnType Table) -SchemaMode $SchemaMode @authArgs
|    Set-SILogDcrRest -AzLogWorkspaceResourceId $AzLogWorkspaceResourceId -SchemaSourceObject (Get-SILogSchemaRest -Data $Data -As Hash -ReturnType DCR) `
|        -DceName $DceName -DcrName $DcrName -DcrResourceGroup $DcrResourceGroup -TableName $TableName -SchemaMode $SchemaMode `
|        -LogIngestServicePricipleObjectId $LogIngestServicePricipleObjectId -AzDcrSetLogIngestApiAppPermissionsDcrLevel $AzDcrSetLogIngestApiAppPermissionsDcrLevel @authArgs
|}
|
|# =====================================================================================================================
|#  REST: upload
|# =====================================================================================================================
|
|function ConvertTo-SILogGzip {
|    param([Parameter(Mandatory)][byte[]]$Bytes)
|    $ms = New-Object System.IO.MemoryStream
|    try {
|        $gz = New-Object System.IO.Compression.GZipStream($ms, [System.IO.Compression.CompressionMode]::Compress, $true)
|        try { $gz.Write($Bytes, 0, $Bytes.Length) } finally { $gz.Dispose() }
|        return , $ms.ToArray()
|    } finally { $ms.Dispose() }
|}
|
|function Send-SILogIngestBatch {
|    <# Posts rows [List of row JSON bytes] as one JSON array. Measured: when the payload (compressed when -State says
|       so) exceeds the limit, the batch is split in two and each half measured again. #>
|    param([Parameter(Mandatory)]$Rows, [Parameter(Mandatory)][hashtable]$State)
|    $raw = New-Object System.IO.MemoryStream
|    try {
|        $raw.WriteByte(0x5B)
|        for ($i = 0; $i -lt $Rows.Count; $i++) { if ($i -gt 0) { $raw.WriteByte(0x2C) }; $b = $Rows[$i]; $raw.Write($b, 0, $b.Length) }
|        $raw.WriteByte(0x5D)
|        $rawBytes = $raw.ToArray()
|    } finally { $raw.Dispose() }
|    $payload = if ($State.Compress) { ConvertTo-SILogGzip -Bytes $rawBytes } else { $rawBytes }
|    if ($payload.Length -gt $State.MaxBytes) {
|        if ($Rows.Count -eq 1) { throw ("A single record ({0} bytes) is larger than the {1}-byte limit of the Log Ingestion API, so it cannot be posted." -f $payload.Length, $State.MaxBytes) }
|        $half = [int][Math]::Floor($Rows.Count / 2)
|        $a = New-Object 'System.Collections.Generic.List[byte[]]'; $z = New-Object 'System.Collections.Generic.List[byte[]]'
|        for ($i = 0; $i -lt $Rows.Count; $i++) { if ($i -lt $half) { [void]$a.Add($Rows[$i]) } else { [void]$z.Add($Rows[$i]) } }
|        Send-SILogIngestBatch -Rows $a -State $State
|        Send-SILogIngestBatch -Rows $z -State $State
|        return
|    }
|    if ($State.Compress -and $rawBytes.Length -gt 0) { $State.Ratio = [Math]::Max(0.01, $payload.Length / $rawBytes.Length) }
|    $from = $State.Posted + 1; $to = $State.Posted + $Rows.Count
|    Write-Host ''
|    Write-Host ("  Posting data to LogAnalytics table [ {0}_CL ]" -f $State.Table)
|    Write-Host ("    Rows       : {0}..{1} / {2}" -f $from, $to, $State.Total)
|    Write-Host ("    {0} | {1}" -f $(if ($State.Compress) { 'Compression=ON' } else { 'Compression=OFF' }), $State.AuthText)
|    Write-Host ''
|    $h = @{}
|    if ($State.Compress) { $h['Content-Encoding'] = 'gzip' }
|    $null = Invoke-SILogIngestRequest -Method POST -Uri $State.Uri -Body ([byte[]]$payload) -ContentType 'application/json' -Headers $h `
|        -Resource 'https://monitor.azure.com/' -Auth $State.Auth -What 'Log Ingestion API request'
|    $State.Posted += $Rows.Count
|    $State.Bytes += [long]$rawBytes.Length
|    $State.Batches++
|    Write-Host '  SUCCESS - data uploaded to LogAnalytics' -ForegroundColor Green
|}
|
|# =====================================================================================================================
|#  REST: the PARALLEL SENDER (#738) -- for a caller that posts one large result in many calls (Risk Analysis)
|#
|#  A large install, 2026-10-17: 1,138,554 Risk Analysis rows reached Log Analytics at ~2,200 rows a minute (~8.5 hours). Every post
|#  was made, and waited for, in line with the work that builds the rows: the page read, the preparation, the JSON, then one
|#  POST at a time, each ~half full (the batch split in two whenever the compressed size went over the limit).
|#  A sender changes only HOW the rows travel, never WHICH rows or their JSON (the rows are serialised exactly as before, by
|#  Send-SILogDataRest, in the order given):
|#    * each POST is filled close to the API's limit: the rows are compressed, the compressed size MEASURED, and a batch that
|#      comes out over the limit gives back its last rows to the next batch (no half batches); the compression ratio adapts
|#      from every measurement; a 413 from the service lowers the limit and the batch is split and sent again;
|#    * up to -Degree POSTs are in flight at once (a small fixed number, 4), each on its own worker; a 429 / 408 / 5xx / no
|#      answer is retried by its worker after the service's Retry-After, and a 429 holds EVERY worker until then;
|#    * the endpoint, the rule and the token are resolved once per sender (the token from the run's cache, refreshed on 401);
|#    * the rows confirmed by the service (2xx) are COUNTED; Complete-SILogIngestSender throws when they are fewer than the
|#      rows handed over -- the same verdict as before. A failed post stops the next hand-over at once (the error is the
|#      same text as a failed synchronous post).
|#  Started by the caller (Start-SILogIngestSender -TableName), then every Send-SILogData for that table goes through it;
|#  any other table, and every caller that never starts one, posts synchronously exactly as before.
|# =====================================================================================================================
|
|function Get-SILogIngestSenderWorkerScript {
|    <# The worker: one POST with the retry rule (working rule 4), holding while the service asked every worker to wait. #>
|    @'
|param([string]$Uri, [byte[]]$Body, [hashtable]$Headers, [int]$MaxAttempts, $Gate)
|$notes = New-Object 'System.Collections.Generic.List[string]'
|for ($attempt = 1; ; $attempt++) {
|    while ($true) {
|        $until = [long]$Gate['PauseUntil']; $now = [datetime]::UtcNow.Ticks
|        if ($until -le $now) { break }
|        Start-Sleep -Milliseconds ([int][Math]::Min(60000, [Math]::Ceiling(($until - $now) / 10000.0)) + 1)
|    }
|    $r = Invoke-SILogIngestHttp -Method POST -Uri $Uri -Headers $Headers -Body $Body -ContentType 'application/json'
|    $code = [int]$r.StatusCode
|    if ($code -ge 200 -and $code -lt 300) { return @{ Code = $code; Attempts = $attempt; Content = ''; Notes = $notes.ToArray() } }
|    $transient = ($code -eq 0 -or $code -eq 408 -or $code -eq 429 -or $code -ge 500)
|    if (-not $transient -or $attempt -ge $MaxAttempts) { return @{ Code = $code; Attempts = $attempt; Content = [string]$r.Content; Notes = $notes.ToArray() } }
|    $wait = Get-SILogIngestRetryDelay -RetryAfter ([string]$r.RetryAfter) -Attempt $attempt
|    if ($code -eq 429) {
|        [System.Threading.Monitor]::Enter($Gate.SyncRoot)
|        try { $t = [datetime]::UtcNow.AddSeconds($wait).Ticks; if ($t -gt [long]$Gate['PauseUntil']) { $Gate['PauseUntil'] = $t } } finally { [System.Threading.Monitor]::Exit($Gate.SyncRoot) }
|    }
|    if ($code -eq 0 -or $wait -ge 30) {
|        $notes.Add((" [INFO] Log Ingestion API request: {0} -- trying again in {1} second(s) (attempt {2} of {3})" -f $(if ($code -eq 0) { 'no answer from Azure' } else { 'Azure answered HTTP {0}' -f $code }), $wait, $attempt, $MaxAttempts))
|    }
|    [System.Threading.Monitor]::Enter($Gate.SyncRoot)
|    try { $Gate['Retries'] = 1 + [int]$Gate['Retries'] } finally { [System.Threading.Monitor]::Exit($Gate.SyncRoot) }
|    Start-Sleep -Seconds $wait
|}
|'@
|}
|
|function Get-SILogIngestSender {
|    <# The sender started for -TableName in this run ($null when none). #>
|    param([Parameter(Mandatory)][string]$TableName)
|    $c = Get-SILogIngestRunCache
|    if (-not ($c.Senders -is [hashtable])) { return $null }
|    $k = ($TableName -replace '_CL$', '').ToLowerInvariant()
|    if ($c.Senders.ContainsKey($k)) { return $c.Senders[$k] }
|    $null
|}
|
|function Get-SILogIngestPostDegree {
|    <# PURE over the setting. POSTs in flight at once: 4 (a small fixed number). SI_LogIngest_ParallelPosts (global) or the
|       environment variable SI_LOGINGEST_PARALLELPOSTS: 1 / 0 / off = one at a time; a number = that many, at most 8. #>
|    param($Setting = $(Get-Variable -Scope Global -Name SI_LogIngest_ParallelPosts -ValueOnly -ErrorAction Ignore), [AllowNull()][AllowEmptyString()][string]$EnvValue = $env:SI_LOGINGEST_PARALLELPOSTS)
|    $s = if ($null -ne $Setting -and ([string]$Setting).Trim() -ne '') { ([string]$Setting).Trim() } elseif ($EnvValue) { $EnvValue.Trim() } else { '' }
|    if ($s -match '^(?i)(off|false|no|disabled?)$') { return 1 }
|    $n = 0
|    if ($s -ne '' -and [int]::TryParse($s, [ref]$n)) { if ($n -le 1) { return 1 }; return [Math]::Min(8, $n) }
|    4
|}
|
|function Start-SILogIngestSender {
|    <# Starts the sender for -TableName (see the block above). -Degree: POSTs in flight at once (Get-SILogIngestPostDegree).
|       -MaxPayloadBytes: the API's limit per call; each POST is filled to -Fill of it (measured after compression). #>
|    param([Parameter(Mandatory)][string]$TableName, [int]$Degree = 0, [long]$MaxPayloadBytes = 1MB, [double]$Fill = 0.95, [int]$MaxAttempts = 6)
|    if ($Degree -le 0) { $Degree = Get-SILogIngestPostDegree }
|    $c = Get-SILogIngestRunCache
|    if (-not ($c.Senders -is [hashtable])) { $c.Senders = @{} }
|    $k = ($TableName -replace '_CL$', '').ToLowerInvariant()
|    if ($c.Senders.ContainsKey($k)) { Stop-SILogIngestSender -TableName $TableName }
|    $s = @{
|        Table = ($TableName -replace '_CL$', ''); Degree = $Degree; MaxBytes = [long]$MaxPayloadBytes; Fill = $Fill; MaxAttempts = $MaxAttempts
|        Uri = $null; Auth = $null; AuthText = ''; Compress = $true; Ratio = 1.0
|        Pending = (New-Object 'System.Collections.Generic.List[byte[]]'); PendingBytes = 2L
|        InFlight = (New-Object 'System.Collections.Generic.List[object]')
|        Accepted = 0L; Dispatched = 0L; Confirmed = 0L; Bytes = 0L; SentBytes = 0L; Posts = 0; Split413 = 0; MaxSent = 0L
|        Failed = $null; Pool = $null; Gate = [hashtable]::Synchronized(@{ PauseUntil = 0L; Retries = 0 }); Script = (Get-SILogIngestSenderWorkerScript)
|    }
|    if ($Degree -gt 1) {
|        # the worker's environment: the HTTP seam and the retry delay AS THEY ARE in this run (a test's fake service
|        # included), and $SILogSeam (the test seam's shared state, $null in a real run). Never a script block of this
|        # runspace: a worker runs only text it was given.
|        $iss = [System.Management.Automation.Runspaces.InitialSessionState]::CreateDefault2()
|        foreach ($fn in 'Invoke-SILogIngestHttp', 'Get-SILogIngestRetryDelay') {
|            $def = (Get-Command -Name $fn -CommandType Function -ErrorAction Stop).Definition
|            $iss.Commands.Add((New-Object System.Management.Automation.Runspaces.SessionStateFunctionEntry($fn, $def)))
|        }
|        $seam = Get-Variable -Scope Global -Name SILogSeam -ValueOnly -ErrorAction Ignore
|        $iss.Variables.Add((New-Object System.Management.Automation.Runspaces.SessionStateVariableEntry('SILogSeam', $seam, '')))
|        $pool = [System.Management.Automation.Runspaces.RunspaceFactory]::CreateRunspacePool(1, $Degree, $iss, $Host)
|        $pool.Open()
|        $s.Pool = $pool
|    }
|    $c.Senders[$k] = $s
|    $s
|}
|
|function Send-SILogIngestSenderBatch {
|    <# Hands one payload to a worker (or posts it here when the sender has no workers), waiting first while -Degree are in flight. #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [Parameter(Mandatory)][byte[]]$Payload, [Parameter(Mandatory)][hashtable]$Batch)
|    while ($Sender.InFlight.Count -ge [Math]::Max(1, $Sender.Degree)) { Receive-SILogIngestSenderResults -Sender $Sender -WaitOne }
|    # once a post has failed, nothing more goes out (the run fails; the rows not posted are counted as not confirmed)
|    if ($Sender.Failed) { return }
|    $token = Get-SILogIngestToken -Resource 'https://monitor.azure.com/' -Auth $Sender.Auth -ForceRefresh:([bool]$Batch.Refresh)
|    $h = @{ 'Authorization' = ('Bearer ' + $token) }
|    if ($Sender.Compress) { $h['Content-Encoding'] = 'gzip' }
|    $Batch.Payload = $Payload
|    $Sender.Posts++
|    if ($null -eq $Sender.Pool) {
|        $res = & ([scriptblock]::Create($Sender.Script)) $Sender.Uri $Payload $h $Sender.MaxAttempts $Sender.Gate
|        Complete-SILogIngestSenderBatch -Sender $Sender -Batch $Batch -Result $res
|        return
|    }
|    $ps = [powershell]::Create()
|    $ps.RunspacePool = $Sender.Pool
|    [void]$ps.AddScript($Sender.Script).AddArgument($Sender.Uri).AddArgument($Payload).AddArgument($h).AddArgument($Sender.MaxAttempts).AddArgument($Sender.Gate)
|    $Batch.PS = $ps
|    $Batch.Handle = $ps.BeginInvoke()
|    [void]$Sender.InFlight.Add($Batch)
|}
|
|function Complete-SILogIngestSenderBatch {
|    <# One post's answer: 2xx = its rows confirmed (said as before); 401 = sent once more with a fresh token; 413 = the limit
|       is lowered and the batch split and sent again; anything else = the sender has FAILED (same text as a failed post). #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [Parameter(Mandatory)][hashtable]$Batch, $Result)
|    $r = $Result
|    if ($r -is [System.Collections.IEnumerable] -and -not ($r -is [hashtable])) { $r = @($r | Where-Object { $_ -is [hashtable] }) | Select-Object -Last 1 }
|    if (-not ($r -is [hashtable])) { $r = @{ Code = 0; Content = 'the post''s worker returned no answer'; Notes = @() } }
|    foreach ($n in @($r.Notes)) { if ($n) { Write-Host $n } }
|    $code = [int]$r.Code
|    if ($code -ge 200 -and $code -lt 300) {
|        $Sender.Confirmed += $Batch.Rows.Count
|        $Sender.Bytes += [long]$Batch.Raw
|        $Sender.SentBytes += [long]$Batch.Payload.Length
|        if ($Batch.Payload.Length -gt $Sender.MaxSent) { $Sender.MaxSent = [long]$Batch.Payload.Length }
|        Write-Host ''
|        Write-Host ("  Posting data to LogAnalytics table [ {0}_CL ]" -f $Sender.Table)
|        Write-Host ("    Rows       : {0}..{1} / {2}" -f $Batch.From, ($Batch.From + $Batch.Rows.Count - 1), $Sender.Accepted)
|        Write-Host ("    {0} | {1} | {2:n0} bytes" -f $(if ($Sender.Compress) { 'Compression=ON' } else { 'Compression=OFF' }), $Sender.AuthText, $Batch.Payload.Length)
|        Write-Host ''
|        Write-Host '  SUCCESS - data uploaded to LogAnalytics' -ForegroundColor Green
|        return
|    }
|    if ($code -eq 401 -and -not $Batch.Refresh -and -not $Sender.Failed) {
|        $Batch.Refresh = $true
|        Send-SILogIngestSenderBatch -Sender $Sender -Payload $Batch.Payload -Batch $Batch
|        return
|    }
|    if ($code -eq 413 -and $Batch.Rows.Count -gt 1 -and -not $Sender.Failed) {
|        # the service's own limit is lower than ours: lower it under this payload and send the rows again in two
|        $Sender.MaxBytes = [long][Math]::Max(65536, [Math]::Floor($Batch.Payload.Length * 0.9))
|        $Sender.Split413++
|        $half = [int][Math]::Floor($Batch.Rows.Count / 2)
|        $a = New-Object 'System.Collections.Generic.List[byte[]]'; $z = New-Object 'System.Collections.Generic.List[byte[]]'
|        for ($i = 0; $i -lt $Batch.Rows.Count; $i++) { if ($i -lt $half) { [void]$a.Add($Batch.Rows[$i]) } else { [void]$z.Add($Batch.Rows[$i]) } }
|        $Sender.Dispatched -= $Batch.Rows.Count
|        Send-SILogIngestSenderRows -Sender $Sender -Rows $a -From $Batch.From
|        Send-SILogIngestSenderRows -Sender $Sender -Rows $z -From ($Batch.From + $half)
|        return
|    }
|    if (-not $Sender.Failed) { $Sender.Failed = ("Log Ingestion API request failed. HTTP Status: {0} Response: {1}" -f $code, $r.Content) }
|}
|
|function Receive-SILogIngestSenderResults {
|    <# Collects the answers of the posts that finished; -WaitOne waits for at least one (when any is in flight); -All for all. #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [switch]$WaitOne, [switch]$All)
|    while ($Sender.InFlight.Count -gt 0) {
|        $done = @($Sender.InFlight | Where-Object { $_.Handle.IsCompleted })
|        if ($done.Count -eq 0) {
|            if (-not $WaitOne -and -not $All) { return }
|            $handles = [System.Threading.WaitHandle[]]@($Sender.InFlight | ForEach-Object { $_.Handle.AsyncWaitHandle } | Select-Object -First 64)
|            [void][System.Threading.WaitHandle]::WaitAny($handles, 1000)
|            continue
|        }
|        # out of the list first: answering one post can send another (401, 413) and wait for the workers again
|        foreach ($b in $done) { [void]$Sender.InFlight.Remove($b) }
|        # each answer on its own: one that throws (a token fetch for a 401 resend, a record too large in a 413 split) is the
|        # sender's FIRST error -- every other finished post is still counted and its worker disposed
|        foreach ($b in $done) {
|            $res = $null
|            try { $res = @($b.PS.EndInvoke($b.Handle)) | ForEach-Object { $_.psobject.BaseObject } | Where-Object { $_ -is [hashtable] } | Select-Object -Last 1 }
|            catch { $res = @{ Code = 0; Content = $_.Exception.Message; Notes = @() } }
|            finally { try { $b.PS.Dispose() } catch { }; $b.PS = $null; $b.Handle = $null }
|            try { Complete-SILogIngestSenderBatch -Sender $Sender -Batch $b -Result $res }
|            catch { if (-not $Sender.Failed) { $Sender.Failed = [string]$_.Exception.Message } }
|        }
|        if ($WaitOne -and -not $All) { return }
|    }
|}
|
|function Send-SILogIngestSenderCut {
|    <# Makes ONE post from the rows waiting: compressed and MEASURED; over the limit -> the last rows wait for the next post
|       (as many as the measurement says), never a half-empty post: a post that measures under 60% of the limit is not
|       sent yet (the ratio is learnt from it and the rows keep coming) -- unless -Final (the rows left at the end). #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [switch]$Final)
|    $rows = $Sender.Pending
|    if ($rows.Count -eq 0) { return }
|    $take = $rows.Count
|    $limit = [long][Math]::Floor($Sender.MaxBytes * $Sender.Fill)
|    while ($true) {
|        $raw = New-Object System.IO.MemoryStream
|        try {
|            $raw.WriteByte(0x5B)
|            for ($i = 0; $i -lt $take; $i++) { if ($i -gt 0) { $raw.WriteByte(0x2C) }; $b = $rows[$i]; $raw.Write($b, 0, $b.Length) }
|            $raw.WriteByte(0x5D)
|            $rawBytes = $raw.ToArray()
|        } finally { $raw.Dispose() }
|        $payload = if ($Sender.Compress) { ConvertTo-SILogGzip -Bytes $rawBytes } else { $rawBytes }
|        if ($Sender.Compress -and $rawBytes.Length -gt 0) { $Sender.Ratio = [Math]::Max(0.005, $payload.Length / [double]$rawBytes.Length) }
|        if (-not $Final -and $take -eq $rows.Count -and $payload.Length -lt [long]($limit * 0.6)) { return }   # too empty yet: wait for more rows
|        if ($payload.Length -le $limit -or ($payload.Length -le $Sender.MaxBytes -and $take -eq 1)) { break }
|        if ($take -eq 1) { throw ("A single record ({0} bytes) is larger than the {1}-byte limit of the Log Ingestion API, so it cannot be posted." -f $payload.Length, $Sender.MaxBytes) }
|        # as many rows as the measured bytes per row allow, a little under (the next post takes the rest)
|        $take = [int][Math]::Max(1, [Math]::Min($take - 1, [Math]::Floor($take * ($limit * 0.98) / [double]$payload.Length)))
|    }
|    $batchRows = $rows.GetRange(0, $take)
|    $rows.RemoveRange(0, $take)
|    $Sender.PendingBytes = 2L; foreach ($b in $rows) { $Sender.PendingBytes += $b.Length + 1 }
|    $from = $Sender.Dispatched + 1
|    $Sender.Dispatched += $take
|    Send-SILogIngestSenderBatch -Sender $Sender -Payload $payload -Batch @{ Rows = $batchRows; Raw = $rawBytes.Length; From = $from; Refresh = $false }
|}
|
|function Send-SILogIngestSenderRows {
|    <# Adds serialised rows to the sender, in order; a post is made each time the rows waiting reach the measured size of a
|       full one. -From: re-sent rows (a 413 split) keep their numbers and go out at once. #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [Parameter(Mandatory)]$Rows, [long]$From = 0)
|    if ($From -gt 0) {
|        # a split batch: these rows go out as they are (each half measured again), ahead of the rows waiting
|        $keep = $Sender.Pending; $keepBytes = $Sender.PendingBytes
|        $Sender.Pending = New-Object 'System.Collections.Generic.List[byte[]]'; foreach ($b in $Rows) { [void]$Sender.Pending.Add($b) }
|        $saved = $Sender.Dispatched; $Sender.Dispatched = $From - 1
|        while ($Sender.Pending.Count -gt 0) { Send-SILogIngestSenderCut -Sender $Sender -Final }
|        $Sender.Dispatched = $saved + $Rows.Count
|        $Sender.Pending = $keep; $Sender.PendingBytes = $keepBytes
|        return
|    }
|    foreach ($b in $Rows) {
|        if (-not $Sender.Compress -and ($b.Length + 2) -gt $Sender.MaxBytes) {
|            throw ("A single record ({0} bytes) is larger than the {1}-byte limit of the Log Ingestion API, so it cannot be posted." -f ($b.Length + 2), $Sender.MaxBytes)
|        }
|        # raw-bytes ceiling: the limit itself uncompressed; compressed, the fill level over the measured ratio
|        $ceiling = if ($Sender.Compress) { [long][Math]::Min(64MB, [Math]::Floor($Sender.MaxBytes * $Sender.Fill / $Sender.Ratio)) } else { [long][Math]::Floor($Sender.MaxBytes * $Sender.Fill) }
|        $add = $b.Length + $(if ($Sender.Pending.Count -gt 0) { 1 } else { 0 })
|        if ($Sender.Pending.Count -gt 0 -and ($Sender.PendingBytes + $add) -gt $ceiling) {
|            Send-SILogIngestSenderCut -Sender $Sender
|            if ($Sender.Failed) { throw $Sender.Failed }
|            $add = $b.Length + $(if ($Sender.Pending.Count -gt 0) { 1 } else { 0 })
|        }
|        [void]$Sender.Pending.Add($b); $Sender.PendingBytes += $add
|        $Sender.Accepted++
|    }
|    Receive-SILogIngestSenderResults -Sender $Sender
|    if ($Sender.Failed) { throw $Sender.Failed }
|}
|
|function Sync-SILogIngestSender {
|    <# Every row handed over is posted and answered (the rows waiting go out now). Throws when a post failed. #>
|    param([Parameter(Mandatory)][hashtable]$Sender)
|    while ($Sender.Pending.Count -gt 0 -and -not $Sender.Failed) { Send-SILogIngestSenderCut -Sender $Sender -Final }
|    Receive-SILogIngestSenderResults -Sender $Sender -All
|    if ($Sender.Failed) { throw $Sender.Failed }
|}
|
|function Invoke-SILogIngestGuardHeal {
|    <#
|        #733 (owner 2026-10-17: guards heal themselves): a table whose rows Log Analytics accepted IN FULL clears an earlier
|        "rows not accepted" of that table by itself. Once per table per process (the first full post), so the hot path pays one
|        state read per table, not one per post. Never throws; nothing when the guard code is not loaded.
|    #>
|    param([Parameter(Mandatory)][string]$Table)
|    try {
|        if (-not (Get-Command -Name Invoke-SIGuardHeal -ErrorAction Ignore)) { return }
|        if ($null -eq $script:SILogIngestHealed) { $script:SILogIngestHealed = @{} }
|        $t = $Table.ToLowerInvariant()
|        if ($script:SILogIngestHealed.ContainsKey($t)) { return }
|        $script:SILogIngestHealed[$t] = $true
|        $null = Invoke-SIGuardHeal -Checked @(@{ GuardId = 'ingest.rows.short-count'; Subject = $Table; Detail = ('Log Analytics accepted every row for {0}.' -f $Table) }) -Complete $true
|    } catch { }
|}
|
|function Complete-SILogIngestSender {
|    <#
|        The end of the hand-over: the rows waiting are posted, every post is answered, the workers are closed. The rows the
|        service CONFIRMED are counted against the rows handed over -- fewer throws (and is a guard event), as a short
|        synchronous post did. Returns @{ RowsPosted; RowsHandedOver; Posts; BytesPosted; BytesSent; MaxBytesSent; Retries; Split413 }.
|    #>
|    param([Parameter(Mandatory)][string]$TableName)
|    $s = Get-SILogIngestSender -TableName $TableName
|    if ($null -eq $s) { return $null }
|    try { Sync-SILogIngestSender -Sender $s }
|    finally { Close-SILogIngestSender -TableName $TableName }
|    if ($s.Confirmed -ne $s.Accepted) {
|        if (Get-Command -Name Send-SIGuardEvent -ErrorAction Ignore) { $null = Send-SIGuardEvent -GuardId 'ingest.rows.short-count' -Outcome 'refused' -Subject ($s.Table + '_CL') -Detail ("Log Analytics accepted {0} of {1} row(s) for {2}_CL." -f $s.Confirmed, $s.Accepted, $s.Table) -Values @(@{ Name = 'rowsPosted'; Label = 'Rows accepted'; Measured = [long]$s.Confirmed; Limit = [long]$s.Accepted }, @{ Name = 'rowsGiven'; Label = 'Rows sent'; Measured = [long]$s.Accepted }) -HeldCount ([long]$s.Accepted - [long]$s.Confirmed) }
|        throw ("Posted {0} of {1} row(s) to {2}_CL -- the other rows are UNKNOWN, not posted." -f $s.Confirmed, $s.Accepted, $s.Table)
|    }
|    if ([long]$s.Accepted -gt 0) { Invoke-SILogIngestGuardHeal -Table ($s.Table + '_CL') }
|    [pscustomobject]@{ RowsPosted = $s.Confirmed; RowsHandedOver = $s.Accepted; Posts = $s.Posts; BytesPosted = $s.Bytes; BytesSent = $s.SentBytes; MaxBytesSent = $s.MaxSent; Retries = [int]$s.Gate['Retries']; Split413 = $s.Split413 }
|}
|
|function Send-SILogDataToSender {
|    <#
|        Send-SILogDataRest's rows through a sender: serialised EXACTLY as the synchronous path does (ConvertTo-Json -Depth 100
|        -Compress per row, UTF-8, in the order given) and handed over. Returns the synchronous path's result shape: RowsPosted
|        = the rows handed over (the rows CONFIRMED are counted by Complete-SILogIngestSender), BytesPosted = their JSON bytes.
|        When this run added columns to the rule and their check is due (Confirm-SILogNewColumns, after this call), every row
|        handed over is posted and answered first -- the check reads the rows back from Log Analytics.
|    #>
|    param([Parameter(Mandatory)][hashtable]$Sender, [Parameter(Mandatory)][AllowEmptyCollection()][array]$Data, [string]$DcrName)
|    # #639: handed over a BATCH at a time -- the rows serialised so far are handed to the sender once they fill a post
|    # (its measured size), never the whole post serialised first and held as bytes beside the rows
|    $list = New-Object 'System.Collections.Generic.List[byte[]]'
|    $bytes = 1L; $count = 0L; $listBytes = 0L
|    $fill = 1.0; if ($Sender.ContainsKey('Fill') -and $Sender.Fill) { $fill = [double]$Sender.Fill }
|    $ratio = 1.0; if ($Sender.ContainsKey('Ratio') -and $Sender.Ratio) { $ratio = [double]$Sender.Ratio }
|    $max = 1MB; if ($Sender.ContainsKey('MaxBytes') -and $Sender.MaxBytes) { $max = [long]$Sender.MaxBytes }
|    $handAt = [long][Math]::Max(1, [Math]::Floor($max * $fill))
|    if ($Sender.Compress) { $handAt = [long][Math]::Min(64MB, [Math]::Floor($max * $fill / $ratio)) }
|    foreach ($row in $Data) {
|        $b = [System.Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -Depth 100 -InputObject $row -Compress))
|        [void]$list.Add($b); $bytes += $b.Length + 1; $listBytes += $b.Length + 1; $count++
|        if ($listBytes -ge $handAt) {
|            Send-SILogIngestSenderRows -Sender $Sender -Rows $list
|            $list = New-Object 'System.Collections.Generic.List[byte[]]'; $listBytes = 0L
|        }
|    }
|    if ($list.Count -gt 0) { Send-SILogIngestSenderRows -Sender $Sender -Rows $list }
|    $list = $null
|    if ($DcrName -and ($global:SI_LogIngestNewColumns -is [hashtable]) -and $global:SI_LogIngestNewColumns.ContainsKey($DcrName.ToLowerInvariant())) {
|        Sync-SILogIngestSender -Sender $Sender
|    }
|    [pscustomobject]@{ StatusCode = 204; RowsPosted = $count; BytesPosted = $bytes; Batches = 0; Table = ($Sender.Table + '_CL'); Stream = '' }
|}
|
|function Stop-SILogIngestSender {
|    <# After a failure: nothing more is posted; the posts in flight are answered (their rows count), the workers closed.
|       Returns the rows the service confirmed (the rows that DID reach Log Analytics). Never throws. #>
|    param([Parameter(Mandatory)][string]$TableName)
|    $s = Get-SILogIngestSender -TableName $TableName
|    if ($null -eq $s) { return 0L }
|    try { $s.Pending.Clear(); Receive-SILogIngestSenderResults -Sender $s -All } catch { }
|    Close-SILogIngestSender -TableName $TableName
|    [long]$s.Confirmed
|}
|
|function Close-SILogIngestSender {
|    param([Parameter(Mandatory)][string]$TableName)
|    $c = Get-SILogIngestRunCache
|    $k = ($TableName -replace '_CL$', '').ToLowerInvariant()
|    if (-not ($c.Senders -is [hashtable]) -or -not $c.Senders.ContainsKey($k)) { return }
|    $s = $c.Senders[$k]
|    foreach ($b in $s.InFlight.ToArray()) { try { if ($b.PS) { $b.PS.Stop(); $b.PS.Dispose() } } catch { } }
|    $s.InFlight.Clear()
|    if ($s.Pool) { try { $s.Pool.Close(); $s.Pool.Dispose() } catch { }; $s.Pool = $null }
|    $c.Senders.Remove($k)
|}
|
|function Send-SILogDataRest {
|    <#
|        Twin of Post-AzLogAnalyticsLogIngestCustomLogDcrDce-Output, over plain REST:
|          * the rule is found by NAME in the configured subscription + SI_DcrResourceGroup (or the one created this run);
|          * the post goes through the endpoint the RULE is bound to -- ingestion accepts nothing else (#199);
|          * POST {endpoint}/dataCollectionRules/{immutableId}/streams/Custom-{table}_CL?api-version=2023-01-01;
|          * batches are sized from the MEASURED JSON bytes of the rows (working rule 5: no fixed row counts), each under
|            the 1 MB limit -- compressed when $global:EnableCompressionDefault says so, measured after compression and
|            split again if over;
|          * 429 / 5xx retried in-run with Retry-After; any other 4xx fails at once with the response body;
|          * the rows posted are COUNTED against the rows given -- a shortfall throws, it is never reported as done.
|        Rows are serialised exactly as the module serialised them (ConvertTo-Json -Depth 100 -Compress per row).
|        -BatchAmount is accepted and ignored: a fixed row count is what working rule 5 forbids.
|    #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][AllowEmptyCollection()][array]$Data, [Parameter(Mandatory)][AllowEmptyString()][string]$DcrName,
|          [AllowEmptyString()][string]$DceName, [Parameter(Mandatory)][string]$TableName,
|          [string]$BatchAmount, [bool]$EnableUploadViaLogHub = $false, [string]$LogHubPath,
|          [string]$AzAppId, [string]$AzAppSecret, [string]$AzAppCertificateThumbprint, [string]$AzAppCertificateStoreLocation = 'LocalMachine', [string]$TenantId,
|          [Nullable[bool]]$EnableCompression = $null, [Nullable[bool]]$UseManagedIdentity = $null, [string]$ManagedIdentityClientId,
|          [string]$SubscriptionId, [string]$DcrResourceGroup, [long]$MaxPayloadBytes = 1MB)
|    $total = @($Data).Count
|    if ($total -eq 0) { return }
|    if ($null -eq $EnableCompression) { $EnableCompression = if ($null -ne $global:EnableCompressionDefault) { [bool]$global:EnableCompressionDefault } else { $false } }
|    $bound = @{}; foreach ($k in $PSBoundParameters.Keys) { $bound[$k] = $PSBoundParameters[$k] }
|    $auth = Resolve-SILogIngestAuth -Bound $bound
|    # #738: a sender started for this table takes the rows (in order, serialised exactly as below); its endpoint, rule and
|    # sign-in are resolved on its first call and reused
|    $sender = Get-SILogIngestSender -TableName $TableName
|    if ($sender -and $sender.Uri) {
|        if ([bool]$EnableCompression -ne [bool]$sender.Compress) { $sender = $null }   # never mixed in one sender
|        else { return (Send-SILogDataToSender -Sender $sender -Data $Data -DcrName $DcrName) }
|    }
|    $scope = Get-SILogIngestScope -SubscriptionId $SubscriptionId -DcrResourceGroup $DcrResourceGroup
|
|    $dcr = Resolve-SILogDcrForTable -DcrName $DcrName -SubscriptionId $scope.Subscription -ResourceGroup $scope.DcrRg -Auth $auth
|    if (-not $dcr) { throw ("Data collection rule '{0}' was not found in resource group '{1}' of subscription '{2}', so nothing was posted." -f $DcrName, $scope.DcrRg, $scope.Subscription) }
|    $immutableId = [string]$dcr.properties.immutableId
|    if (-not $immutableId) { throw ("Data collection rule '{0}' has no immutable id yet, so nothing was posted." -f $DcrName) }
|    $stream = Get-SILogStreamName -TableName $TableName
|    if (-not ($dcr.properties.streamDeclarations -and $dcr.properties.streamDeclarations.PSObject.Properties[$stream])) {
|        $first = @(@($dcr.properties.dataFlows)[0].streams)[0]
|        if ($first) { $stream = [string]$first }
|    }
|    $endpoint = $null
|    $boundDce = [string]$dcr.properties.dataCollectionEndpointId
|    if ($boundDce) {
|        $dce = Invoke-SILogArm -Path $boundDce -ApiVersion (Get-SILogArmApiVersion Dce) -Auth $auth -AllowNotFound
|        if ($dce) { $endpoint = [string]$dce.properties.logsIngestion.endpoint }
|    }
|    if (-not $endpoint -and $dcr.properties.endpoints -and $dcr.properties.endpoints.logsIngestion) { $endpoint = [string]$dcr.properties.endpoints.logsIngestion }
|    if (-not $endpoint -and $DceName) {
|        $dce = Find-SILogResourceByName -Kind Dce -Name $DceName -SubscriptionId $scope.Subscription -ResourceGroup $scope.DceRg -Auth $auth -AnyResourceGroupWhenMissing
|        if ($dce) { $endpoint = [string]$dce.properties.logsIngestion.endpoint }
|    }
|    if (-not $endpoint) { throw ("No ingestion endpoint for data collection rule '{0}' (not bound to an endpoint, and '{1}' was not found), so nothing was posted." -f $DcrName, $DceName) }
|
|    $authText = switch ($auth.Mode) { 'ManagedIdentity' { 'Auth=ManagedIdentity' } 'Certificate' { 'Auth=SPN-Cert' } 'Secret' { 'Auth=SPN' } 'Support' { 'Auth=InvardiaSupport' } default { 'Auth=Run' } }
|    $state = @{
|        Uri = ('{0}/dataCollectionRules/{1}/streams/{2}?api-version=2023-01-01' -f $endpoint.TrimEnd('/'), $immutableId, $stream)
|        Auth = $auth; Compress = [bool]$EnableCompression; MaxBytes = $MaxPayloadBytes; Ratio = 1.0
|        Posted = 0; Bytes = 0L; Batches = 0; Total = $total; Table = $TableName; AuthText = $authText
|    }
|    if ($sender) {
|        $sender.Uri = $state.Uri; $sender.Auth = $auth; $sender.AuthText = $authText; $sender.Compress = [bool]$EnableCompression
|        $sender.MaxBytes = [long][Math]::Min([double]$sender.MaxBytes, [double]$MaxPayloadBytes)
|        return (Send-SILogDataToSender -Sender $sender -Data $Data -DcrName $DcrName)
|    }
|    $batch = New-Object 'System.Collections.Generic.List[byte[]]'
|    $batchBytes = 2
|    foreach ($row in $Data) {
|        $b = [System.Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -Depth 100 -InputObject $row -Compress))
|        if (-not $state.Compress -and ($b.Length + 2) -gt $MaxPayloadBytes) {
|            throw ("A single record ({0} bytes) is larger than the {1}-byte limit of the Log Ingestion API, so it cannot be posted." -f ($b.Length + 2), $MaxPayloadBytes)
|        }
|        # raw-bytes ceiling: the limit itself uncompressed; compressed, the limit over the measured ratio (90% margin)
|        $ceiling = if ($state.Compress) { [long][Math]::Min(64MB, [Math]::Floor($MaxPayloadBytes / $state.Ratio * 0.9)) } else { $MaxPayloadBytes }
|        $add = $b.Length + $(if ($batch.Count -gt 0) { 1 } else { 0 })
|        if ($batch.Count -gt 0 -and ($batchBytes + $add) -gt $ceiling) {
|            Send-SILogIngestBatch -Rows $batch -State $state
|            $batch = New-Object 'System.Collections.Generic.List[byte[]]'; $batchBytes = 2; $add = $b.Length
|        }
|        [void]$batch.Add($b); $batchBytes += $add
|    }
|    if ($batch.Count -gt 0) { Send-SILogIngestBatch -Rows $batch -State $state }
|    if ($state.Posted -ne $total) {
|        # #277: the short count is a guard trip -- mailed and reported (never instead of the throw)
|        if (Get-Command -Name Send-SIGuardEvent -ErrorAction Ignore) { $null = Send-SIGuardEvent -GuardId 'ingest.rows.short-count' -Outcome 'refused' -Subject ($TableName + '_CL') -Detail ("Log Analytics accepted {0} of {1} row(s) for {2}_CL." -f $state.Posted, $total, $TableName) -Values @(@{ Name = 'rowsPosted'; Label = 'Rows accepted'; Measured = [long]$state.Posted; Limit = [long]$total }, @{ Name = 'rowsGiven'; Label = 'Rows sent'; Measured = [long]$total }) -HeldCount ([long]$total - [long]$state.Posted) }
|        throw ("Posted {0} of {1} row(s) to {2}_CL -- the other rows are UNKNOWN, not posted." -f $state.Posted, $total, $TableName)
|    }
|    if ([long]$total -gt 0) { Invoke-SILogIngestGuardHeal -Table ($TableName + '_CL') }
|    # BytesPosted: the uncompressed JSON bytes of the rows posted -- a caller that posts in parts sizes its next part from it
|    return [pscustomobject]@{ StatusCode = 204; RowsPosted = $state.Posted; BytesPosted = $state.Bytes; Batches = $state.Batches; Table = ($TableName + '_CL'); Stream = $stream }
|}
'@ }
$__siSupportFiles['auth/Find-SICertificate.ps1'] = @{ Sha256 = '3778fc328c239b499738360e6b4fb31eb3109db39c3a9a9d8f5a02a228ad58d8'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- find the engine SPN's certificate on ANY host, and bring one into a container (#209).
|
|    KEY POINT: THE `Cert:` DRIVE IS A WINDOWS CONVENIENCE; [X509Store] IS THE AUTHORITY. The drive does not exist
|    in a Linux container at all (pwsh on Linux has no certificate provider), and on Windows it can vanish
|    from a PS 5.1 child that inherited a pwsh 7 PSModulePath (framework finding AUTH-1). Five ingest sites
|    looked a thumbprint up through the drive ONLY, so in a container the lookup always "missed", the store
|    location fell back to LocalMachine, and certificate sign-in could not work there at all.
|
|    Every function here uses the drive when it exists -- exactly what the engines did before -- and the
|    X509Store only when it does not, so a Windows VM with its certificate in LocalMachine\My resolves the
|    same certificate, from the same store, as it always has.
|
|    Functions:
|      Get-SICertificateFromStore    -- one thumbprint -> @{ Certificate; StoreLocation } or $null
|      Get-SICertStoreLocation       -- 'LocalMachine' / 'CurrentUser' for the log-ingestion sign-in (default LocalMachine)
|      Get-SICertificateClientToken  -- client_credentials with a certificate-signed assertion (no Cert: drive)
|      Import-SIContainerCertificate -- a base64 PFX (Key Vault reference) -> CurrentUser\My + a PFX file
|
|    PS 5.1 safe: no ?. / ??, no ImportFromPem.
|#>
|
|function Test-SICertDriveAvailable {
|    <# The Windows certificate provider is loaded in this process. A seam for the tests. #>
|    return [bool](Get-PSDrive -Name Cert -ErrorAction SilentlyContinue)
|}
|
|function Get-SICertificateFromStore {
|    <#
|        Find a certificate WITH a private key by thumbprint, LocalMachine first, then CurrentUser -- the order
|        every SI engine already used. Returns @{ Certificate; StoreLocation } or $null.
|
|        -HasCertDrive and -OpenStore are test seams: -OpenStore takes a store location and returns the
|        certificates in its My store.
|    #>
|    param(
|        [Parameter(Mandatory)][AllowEmptyString()][string]$Thumbprint,
|        [string[]]$StoreLocations = @('LocalMachine', 'CurrentUser'),
|        [scriptblock]$HasCertDrive,
|        [scriptblock]$OpenStore
|    )
|    $clean = ($Thumbprint -replace '\s', '').ToUpperInvariant()
|    if ([string]::IsNullOrWhiteSpace($clean)) { return $null }
|    if (-not $HasCertDrive) { $HasCertDrive = { Test-SICertDriveAvailable } }
|    if (-not $OpenStore) {
|        $OpenStore = {
|            param([string]$Location)
|            $x = New-Object System.Security.Cryptography.X509Certificates.X509Store('My', $Location)
|            try {
|                $x.Open('ReadOnly')
|                return @($x.Certificates)
|            } finally { $x.Close() }
|        }
|    }
|    $drive = [bool](& $HasCertDrive)
|    foreach ($loc in $StoreLocations) {
|        $found = $null
|        if ($drive) {
|            $found = Get-ChildItem "Cert:\$loc\My" -ErrorAction SilentlyContinue |
|                     Where-Object { $_.Thumbprint -eq $clean -and $_.HasPrivateKey } |
|                     Select-Object -First 1
|        } else {
|            try {
|                $found = @(& $OpenStore $loc | Where-Object { $_ -and $_.Thumbprint -eq $clean -and $_.HasPrivateKey })[0]
|            } catch {
|                Write-Verbose ("certificate store {0}\My unreadable: {1}" -f $loc, $_.Exception.Message)
|            }
|        }
|        if ($found) { return [pscustomobject]@{ Certificate = $found; StoreLocation = $loc } }
|    }
|    return $null
|}
|
|function Get-SICertStoreLocation {
|    <#
|        The store the log-ingestion sign-in should be told to look in. Same answer the five ingest sites computed
|        through the Cert: drive (LocalMachine when nothing is found), now also right where the drive is
|        missing.
|    #>
|    param(
|        [Parameter(Mandatory)][AllowEmptyString()][string]$Thumbprint,
|        [scriptblock]$HasCertDrive,
|        [scriptblock]$OpenStore
|    )
|    $hit = Get-SICertificateFromStore -Thumbprint $Thumbprint -HasCertDrive $HasCertDrive -OpenStore $OpenStore
|    if ($hit) { return [string]$hit.StoreLocation }
|    return 'LocalMachine'
|}
|
|function Get-SICertificateClientToken {
|    <#
|        An access token for -Resource via client_credentials with a certificate-signed JWT assertion -- the
|        grant Get-SIGraphToken and the log ingestion already use, without the Cert: drive. Returns the
|        token string. -Invoke is a test seam: { param($Uri, $Body) } returning the token response.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$TenantId,
|        [Parameter(Mandatory)][string]$ClientId,
|        [Parameter(Mandatory)][string]$Thumbprint,
|        [Parameter(Mandatory)][string]$Resource,
|        [scriptblock]$Invoke
|    )
|    $hit = Get-SICertificateFromStore -Thumbprint $Thumbprint
|    if (-not $hit) { throw ("certificate '{0}' was not found with a private key in LocalMachine\My or CurrentUser\My." -f (($Thumbprint -replace '\s', '').ToUpperInvariant())) }
|    $cert = $hit.Certificate
|
|    $scope = if ($Resource -match '/\.default$') { $Resource } else { ($Resource.TrimEnd('/') + '/.default') }
|    $tokenUri = 'https://login.microsoftonline.com/{0}/oauth2/v2.0/token' -f $TenantId
|    $b64url = { param([byte[]]$Bytes) [Convert]::ToBase64String($Bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_') }
|    $now = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
|    $header = @{ alg = 'RS256'; typ = 'JWT'; x5t = (& $b64url $cert.GetCertHash()) } | ConvertTo-Json -Compress
|    $claims = @{ aud = $tokenUri; iss = $ClientId; sub = $ClientId; jti = [guid]::NewGuid().ToString(); nbf = $now; exp = ($now + 600) } | ConvertTo-Json -Compress
|    $enc = [System.Text.Encoding]::UTF8
|    $unsigned = '{0}.{1}' -f (& $b64url $enc.GetBytes($header)), (& $b64url $enc.GetBytes($claims))
|    $rsa = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
|    if (-not $rsa) { throw ("certificate '{0}' has no usable RSA private key." -f $cert.Thumbprint) }
|    $sig = $rsa.SignData($enc.GetBytes($unsigned), [System.Security.Cryptography.HashAlgorithmName]::SHA256, [System.Security.Cryptography.RSASignaturePadding]::Pkcs1)
|    $body = @{
|        client_id             = $ClientId
|        scope                 = $scope
|        client_assertion_type = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
|        client_assertion      = ('{0}.{1}' -f $unsigned, (& $b64url $sig))
|        grant_type            = 'client_credentials'
|    }
|    $resp = if ($Invoke) { & $Invoke $tokenUri $body }
|            # a time limit: without one this call waits for as long as the other side stays silent (PowerShell 7 has no default)
|            else { Invoke-RestMethod -Method Post -Uri $tokenUri -Body $body -ContentType 'application/x-www-form-urlencoded' -TimeoutSec 60 }
|    if (-not $resp.access_token) { throw 'the token endpoint returned no access_token.' }
|    return [string]$resp.access_token
|}
|
|function Get-SIContainerCertificateKeyFlags {
|    <# PURE. The key flags the container imports the SPN's PFX with: Exportable + PersistKeySet (the store keeps the key for
|       the life of the run). One place, so a test can pin them. #>
|    [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable -bor
|        [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::PersistKeySet
|}
|
|function Import-SIContainerCertificate {
|    <#
|        CONTAINER ONLY. The SPN's PFX arrives as a Key Vault-referenced secret (base64), exactly as the SI
|        updater receives its own. This puts it where every engine looks:
|          * CurrentUser\My, through [X509Store] (the only certificate store a Linux container has), so
|            Get-SIGraphToken, the ledger and the log ingestion find it by thumbprint;
|          * a PFX file (owner-only), so Connect-SIAzAccount -CertificatePath can sign in with it -- az and
|            the sign-in remember the PATH, not the key, so the file is kept for the life of the run.
|        Returns @{ Thumbprint; PfxPath }. Never prints the certificate or its password.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$PfxBase64,
|        [string]$Password,
|        [string]$Directory = [IO.Path]::GetTempPath(),
|        [switch]$SkipStore,
|        # TESTS ONLY: a Windows test session that cannot persist a private key (no DPAPI master key) imports with
|        # EphemeralKeySet instead. No caller in the product passes it: the container always uses Get-SIContainerCertificateKeyFlags.
|        [Parameter(DontShow)][AllowNull()][Nullable[System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]]$KeyStorageFlags = $null
|    )
|    $bytes = [Convert]::FromBase64String(($PfxBase64 -replace '\s', ''))
|    $flags = if ($null -ne $KeyStorageFlags) { [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]$KeyStorageFlags } else { Get-SIContainerCertificateKeyFlags }
|    # A Key Vault certificate's secret is a password-less PFX; '' opens those on both .NET hosts.
|    $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($bytes, [string]$Password, $flags)
|    if (-not $cert.HasPrivateKey) { throw 'the SPN certificate (SI_SPN_CERT_PFX_B64) carries no private key.' }
|
|    if (-not $SkipStore) {
|        $store = New-Object System.Security.Cryptography.X509Certificates.X509Store('My', 'CurrentUser')
|        try {
|            $store.Open('ReadWrite')
|            $store.Add($cert)
|        } finally { $store.Close() }
|    }
|
|    $pfxPath = Join-Path $Directory ('si-spn-' + [guid]::NewGuid().ToString('N') + '.pfx')
|    [IO.File]::WriteAllBytes($pfxPath, $bytes)
|    if ($PSVersionTable.PSVersion.Major -ge 6 -and -not $IsWindows) { try { & chmod 600 $pfxPath } catch { } }
|    return [pscustomobject]@{ Thumbprint = [string]$cert.Thumbprint; PfxPath = $pfxPath }
|}
'@ }
$__siSupportFiles['engine/_shared/SI-ErrorClass.ps1'] = @{ Sha256 = 'ab3ed267218c640b0e672f593af5d33a61146cc96980f39dc70ee56e2f8bd92d'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- WHAT KIND OF FAILURE WAS IT: one error class per failed run, for the telemetry `run` record.
|
|    ExitReason says only success / success-partial / error / settings-error. A release-health view needs to tell "a
|    permission is missing" from "the service was throttling" from "the query is broken", without free text (anonymous
|    installs send no error text at all). Get-SIErrorClass maps an error to exactly ONE value of a CLOSED list -- the list
|    agreed with the receiving side; anything not recognised is 'unknown', never a guess.
|
|    It is built on the classifiers SecurityInsight already trusts:
|      * SI-KqlError.ps1 -- what a Log Analytics failure REALLY said (the response body, not "BadRequest") and whether
|        it was a missing table;
|      * working rule 4 / Risk Analysis' bucket classifier -- the recognised PLATFORM prefixes (a cancellation or a
|        service-side entity resolution carries the service's generic "Fix semantic errors" tail and is NOT a query
|        defect), then syntax / semantic / type errors = query defect, then throttle, then timeout / 5xx.
|
|    The order of the checks is the contract (first match wins):
|      settings-error > guard-refused > out-of-memory > database-full > licence-invalid > mi-unavailable > sql-login > config-missing > ingest-short-count >
|      table-missing > platform prefix (timeout / 5xx) > kql-query-defect > throttled > ingest-4xx >
|      401 / 403 by service > ai-error > platform-timeout > platform-5xx > unknown.
|    A 401 from Microsoft Graph is graph-401; a 401 from another service means the same thing as its 403 there (access
|    refused) and gets that service's -403 class.
|
|    PURE. No network. PS 5.1 safe.
|#>
|
|if (-not (Get-Command -Name Get-SIKqlErrorText -ErrorAction SilentlyContinue)) {
|    . ([System.IO.Path]::Combine($PSScriptRoot, 'SI-KqlError.ps1'))
|}
|
|# The closed list, exactly as agreed (#226). Get-SIErrorClass returns one of these and nothing else.
|function Get-SIErrorClassesState {
|    <# The value of $script:SIErrorClasses, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SIErrorClasses) { $script:SIErrorClasses = @(
|    'graph-401', 'graph-403', 'defender-403', 'arm-403', 'kv-403', 'storage-403', 'sql-login', 'mi-unavailable',
|    'throttled', 'platform-timeout', 'platform-5xx', 'kql-query-defect', 'table-missing', 'ingest-4xx',
|    'ingest-short-count', 'settings-error', 'config-missing', 'licence-invalid', 'ai-error',
|    # UPLINK-FIX (Invardia, 2026-10-07): a run a guard REFUSED (nothing written, by design). The run's message is
|    # '<guard id> refused: <why>' (Get-SIGuardRefusalText) -- its own class, so a refusal never reads as 'unknown'.
|    'guard-refused',
|    # #641 (owner 2026-10-13): a Risk Analysis report that is NOT COMPLETE in its run (its rows do not match what the source
|    # holds, or it is not in the run at all) -- set by Risk Analysis itself, never derived from a message
|    'report-incomplete',
|    # #702 (1) (customer B 2026-10-15): the process ran out of memory. Its own class, never platform-timeout -- a platform
|    # class is retried in-run on the same size, which runs out again; the job-size rule raises the job one band instead.
|    # (Invardia's receiver takes any ^[a-z0-9-]{1,40}$ class -- packages/core/src/uplink.ts.)
|    'out-of-memory',
|    # #904 (a large install 2026-10-26): Azure SQL refused a write because the database reached its maximum size (1105,
|    # 40544, "has reached its size quota"). Its own class -- never 'unknown' -- so a part that failed on it opens a ticket.
|    'database-full',
|    # #913 (the ride test install 2026-10-27): an Azure SQL transient (9001 log not available, 40613 / 40501 / 40197 /
|    # 49918-49920, 4060 during a failover, 10928 / 10929, a reset connection) that did not pass within its bounded retry.
|    # Set by the caller that retried it (the pipeline runner's lock), never derived from a text: not a product defect.
|    'transient-sql',
|    # 3.0.30: the web app's identity has no grant on its Key Vault key (the updater only checks it; setup makes it) -- the
|    # customer's action with the command, never arm-403 (that is a real 403 answer). Set by the caller, never derived from a text.
|    'grant-missing',
|    'unknown'
|) }
|    , $script:SIErrorClasses
|}
|$script:SIErrorClasses = $null; $null = Get-SIErrorClassesState
|
|# #904: the numbers of Azure SQL's "the database is full" refusal (1105: no space in the filegroup; 40544: the database
|# reached its size quota; 1101: no new page could be allocated)
|function Get-SIDatabaseFullNumbersState {
|    <# The value of $script:SIDatabaseFullNumbers, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SIDatabaseFullNumbers) { $script:SIDatabaseFullNumbers = @(1105, 40544, 1101) }
|    , $script:SIDatabaseFullNumbers
|}
|$script:SIDatabaseFullNumbers = $null; $null = Get-SIDatabaseFullNumbersState
|
|# Risk Analysis' recognised platform-failure prefixes (RA-GraphHunting.ps1, $script:RAPlatformFailurePrefixes). Read
|# from there when Risk Analysis is loaded, so the two can never disagree; this copy serves every other engine. A test
|# compares the two lists.
|function Get-SIErrorPlatformPrefixesState {
|    <# The value of $script:SIErrorPlatformPrefixes, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SIErrorPlatformPrefixes) { $script:SIErrorPlatformPrefixes = @(
|    @{ Pattern = 'Query cancelled on creation'; Class = 'platform-timeout' }
|    @{ Pattern = 'ScalarEvaluator\.Evaluate failed'; Class = 'platform-timeout' }
|    @{ Pattern = 'Errors occurred while resolving remote entities'; Class = 'platform-5xx' }
|) }
|    , $script:SIErrorPlatformPrefixes
|}
|$script:SIErrorPlatformPrefixes = $null; $null = Get-SIErrorPlatformPrefixesState
|
|function Get-SIErrorClasses { (Get-SIErrorClassesState) }
|
|function Test-SIDatabaseFullError {
|    <#
|        PURE. #904: did Azure SQL refuse a write because the database is FULL? -Value: an ErrorRecord, an exception (its
|        SqlException numbers and inner exceptions are read) or a text. SQL 1105 / 40544 / 1101, "has reached its size quota",
|        "filegroup is full", "Could not allocate space" / "Could not allocate a new page".
|    #>
|    param([AllowNull()]$Value)
|    if ($null -eq $Value) { return $false }
|    $ex = if ($Value -is [System.Exception]) { $Value } elseif ($Value -is [System.Management.Automation.ErrorRecord]) { $Value.Exception } else { $null }
|    $texts = New-Object System.Collections.Generic.List[string]
|    while ($ex) {
|        if ($ex -is [System.Data.SqlClient.SqlException]) { foreach ($er in @($ex.Errors)) { if ((Get-SIDatabaseFullNumbersState) -contains [int]$er.Number) { return $true } } }
|        $texts.Add([string]$ex.Message); $ex = $ex.InnerException
|    }
|    if (-not $texts.Count) { $texts.Add([string]$Value) }
|    $t = $texts -join ' | '
|    return [bool]($t -match '(?i)has reached its size quota|filegroup is full|Could not allocate (space|a new page)|\b(Error|Msg|Number)[ :=]*(1105|40544)\b|\((1105|40544)\)')
|}
|
|function Get-SITransientKind {
|    <#
|        PURE. THE ONE DECISION of what a failed call or a failure text REALLY was (2026-10-22: a "Connection timed out" to
|        SI's own storage was reported to the owner as "Microsoft throttled this run"):
|          throttled    Microsoft asked us to slow down -- ONLY a real throttling answer: HTTP 429, "Too Many Requests", a
|                       rate limit, SQL 40501 / 10928 / 10929 (the service is busy / resource limit)
|          timeout      no answer in time: HTTP 408 / 504, SQL -2, "timed out" / "timeout" / a cancelled task
|          unavailable  the service could not be reached or failed: HTTP 500 / 502 / 503, no answer at all (status 0 without a
|                       timeout), a reset / refused / closed connection, a host that does not resolve, SQL 40613 / 40197 /
|                       49918-49920 / 10053 / 10054 / 233 / 64
|          error        anything else (a refusal, a bug, a bad request) -- never retried as transient
|        -StatusCode (an HTTP status; 0 = no answer; -1 = not known), -Message (the error text), -SqlNumber (SqlException numbers).
|        SecurityInsight's OWN customer sentence ("Microsoft throttled this run ...") is taken out of the text first, so a
|        re-read log never classifies itself.
|    #>
|    param([int]$StatusCode = -1, [AllowNull()][AllowEmptyString()][string]$Message = '', [AllowNull()][int[]]$SqlNumber = @())
|    $t = ([string]$Message) -replace '(?i)Microsoft throttled this run[^|]*', ''
|    $sql = @($SqlNumber | Where-Object { $null -ne $_ })
|    if ($StatusCode -eq 429 -or @($sql | Where-Object { $_ -in 40501, 10928, 10929 }).Count -gt 0) { return 'throttled' }
|    if ($t -match '(?i)\b429\b|Too ?Many ?Requests|\bthrottl|rate limit|RequestRateTooLarge') { return 'throttled' }
|    if ($StatusCode -in 408, 504 -or $sql -contains -2) { return 'timeout' }
|    if ($t -match '(?i)timed? ?out|timeout|TaskCanceledException|A task was canceled|operation was canceled|\b504\b|Gateway Time-?out|\b408\b') { return 'timeout' }
|    if ($StatusCode -in 500, 502, 503 -or $StatusCode -eq 0 -or @($sql | Where-Object { $_ -in 40613, 40197, 49918, 49919, 49920, 10053, 10054, 233, 64 }).Count -gt 0) { return 'unavailable' }
|    if ($t -match '(?i)\b50[0-3]\b|Internal ?Server ?Error|Bad Gateway|Service ?Unavailable|ServiceUnavailable|temporarily unavailable|is not currently available|forcibly closed|connection (was )?reset|Connection reset by peer|actively refused|No such host is known|Name or service not known|transport-level error|Unable to connect to the remote server') { return 'unavailable' }
|    'error'
|}
|
|function Test-SIOutOfMemoryText {
|    <# PURE. Does a failure text (or an exception / ErrorRecord, read with its inner exceptions) say the process ran out of
|       memory? .NET's OutOfMemoryException (also wrapped: "Exception calling ... : Exception of type
|       'System.OutOfMemoryException' was thrown", "Cannot process argument transformation on parameter 'TimeoutSec'. ..."),
|       Container Apps' OOMKilled, or SecurityInsight's own "out of memory" wording. #702 (1). #>
|    param([AllowNull()]$Value)
|    if ($null -eq $Value) { return $false }
|    $ex = if ($Value -is [System.Exception]) { $Value } elseif ($Value -is [System.Management.Automation.ErrorRecord]) { $Value.Exception } else { $null }
|    while ($ex) { if ($ex -is [System.OutOfMemoryException]) { return $true }; $ex = $ex.InnerException }
|    $t = if ($Value -is [System.Management.Automation.ErrorRecord]) { [string]$Value.Exception } else { [string]$Value }
|    return [bool]($t -match '(?i)OutOfMemoryException|\bOOMKilled\b|\bout of memory\b')
|}
|
|# WHO FIXES IT (framework §8.5 CLOSE-LOOP, Invardia 046): the classes whose fix is the CUSTOMER's configuration -- a
|# permission or consent the install's identity does not have (the five -403 classes), a licence or licensed feature it
|# lacks (licence-invalid), a setting the customer must set (config-missing, settings-error). Everything else -- sign-in
|# and token trouble, a missing table, ingestion, throttling, timeouts, service errors, guard refusals, unknown -- stays a
|# product defect: a class is put here only when its own definition above says the customer's configuration is the cause.
|function Get-SICustomerConfigClassesState {
|    <# The value of $script:SICustomerConfigClasses, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SICustomerConfigClasses) { $script:SICustomerConfigClasses = @('graph-403', 'defender-403', 'arm-403', 'kv-403', 'storage-403', 'licence-invalid', 'config-missing', 'settings-error', 'grant-missing') }
|    , $script:SICustomerConfigClasses
|}
|$script:SICustomerConfigClasses = $null; $null = Get-SICustomerConfigClassesState
|# #913: the classes that are nobody's fix -- an Azure SQL transient that did not pass within its bounded retry. No FixKind:
|# never a fix request, never a red alert (the next wake-up runs as usual).
|function Get-SINoFixClassesState {
|    <# The value of $script:SINoFixClasses, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SINoFixClasses) { $script:SINoFixClasses = @('transient-sql') }
|    , $script:SINoFixClasses
|}
|$script:SINoFixClasses = $null; $null = Get-SINoFixClassesState
|
|function Get-SICustomerConfigClasses { (Get-SICustomerConfigClassesState) }
|
|function Get-SIErrorFixKind {
|    <#
|        PURE. The FixKind of a failed report's error class: 'customer-config' for a class on the customer-configuration list,
|        'product-defect' for every other class of the closed list (and anything not on it), '' when there is no class.
|    #>
|    param([AllowEmptyString()][AllowNull()][string]$ErrorClass)
|    $c = "$ErrorClass".Trim().ToLowerInvariant()
|    if (-not $c) { return '' }
|    if ((Get-SINoFixClassesState) -contains $c) { return '' }
|    if ((Get-SICustomerConfigClassesState) -contains $c) { return 'customer-config' }
|    'product-defect'
|}
|
|function Get-SIErrorService {
|    <# PURE. Which service a failure came from, by the host or the wording it carries: graph | defender | arm | kv |
|       storage | sql | ingest | ai | loganalytics | ''. #>
|    param([AllowEmptyString()][string]$Text)
|    $t = [string]$Text
|    if ($t -match '(?i)ingest\.monitor\.azure\.com|Logs Ingestion|log ingestion|dataCollectionRules|\bDCR\b|\bDCE\b|InvalidTransformOutput') { return 'ingest' }
|    if ($t -match '(?i)openai\.azure\.com|\bOpenAI\b|content_filter|context_length_exceeded|DeploymentNotFound|chat/completions') { return 'ai' }
|    if ($t -match '(?i)api\.securitycenter\.microsoft\.com|api\.security\.microsoft\.com|security/runHuntingQuery|advanced hunting|Microsoft Defender|\bMachine\.Read\.All\b|\bThreatHunting\.Read\.All\b') { return 'defender' }
|    if ($t -match '(?i)\.vault\.azure\.net|Key ?Vault|ForbiddenByRbac|ForbiddenByPolicy|secrets get permission|getSecret/action') { return 'kv' }
|    if ($t -match '(?i)\.(blob|table|queue|file|dfs)\.core\.windows\.net|AuthorizationPermissionMismatch|AuthorizationFailure|storage account') { return 'storage' }
|    if ($t -match '(?i)database\.windows\.net|SqlException|SqlClient|\bLogin failed\b') { return 'sql' }
|    if ($t -match '(?i)management\.azure\.com|AuthorizationFailed|Microsoft\.[A-Za-z]+/[A-Za-z]+/[A-Za-z/]*(read|write|action)|\bAzure Resource Manager\b|LinkedAuthorizationFailed') { return 'arm' }
|    if ($t -match '(?i)graph\.microsoft\.com|Authorization_RequestDenied|Microsoft Graph|InvalidAuthenticationToken') { return 'graph' }
|    if ($t -match '(?i)api\.loganalytics|loganalytics\.io|Log Analytics|SEM\d{4}|SYN\d{4}') { return 'loganalytics' }
|    ''
|}
|
|function Get-SIErrorLines {
|    <#
|        PURE. A failed run's own words from its log (a run transcript, a console tail): the error that ENDED it -- the LAST
|        [ERROR] / exception / failed / refused / denied / status-code block (transcript TerminatingError markers and WARNING:
|        lines only when nothing else is there), and the lines after it up to -Max, else -- no such line --
|        the LAST -Max lines that carry text. Transcript headers / footers and the ******** frames are dropped. Never the whole
|        log: the uplink carries a few lines, and the caller redacts them (ConvertTo-AitUplinkRedacted). '' for no text.
|    #>
|    param([AllowNull()][AllowEmptyCollection()][string[]]$Lines = @(), [int]$Max = 8, [int]$MaxChars = 1800)
|    $keep = New-Object System.Collections.Generic.List[string]
|    $inHeader = $false
|    foreach ($raw in @($Lines)) {
|        $l = ([string]$raw).TrimEnd()
|        if (-not $l.Trim()) { continue }
|        if ($l -match '^\*{10,}$') { $inHeader = -not $inHeader; continue }
|        if ($inHeader) { continue }
|        if ($l -match '^(PowerShell|Windows PowerShell) transcript (start|end)|^(Start|End) time: \d{14}|^Transcript started, output file is') { continue }
|        $keep.Add($l.Trim())
|    }
|    if (-not $keep.Count) { return '' }
|    $err = '(?i)\[(ERROR|FAIL(ED)?|FATAL)\]|\bERROR\b|Exception|\bfailed\b|could not|cannot|refused|denied|Forbidden|Unauthorized|Login failed|\b(40[0-9]|429|50[0-4])\b|throttl|timed? ?out'
|    # The error that ENDED the run, not the first one in the log: every error-looking line is a candidate; the
|    # transcript's own "PS>TerminatingError(...)" / ">> TerminatingError(...)" markers (written for an error the code
|    # CAUGHT and went on after) and WARNING: lines count only when the log has no other error line. The LAST such line
|    # is taken, from the start of its block (the error lines right before it), and the lines after it up to -Max.
|    $isErr = { param($s) $s -match $err -and $s -notmatch '(?i)^\s*(VERBOSE|DEBUG)\b|\b0 (failed|errors?)\b' }
|    $isWeak = { param($s) $s -match '(?i)^\s*(PS>|>>\s*)TerminatingError\(|^\s*WARNING:' }
|    $strong = -1; $weak = -1
|    for ($i = 0; $i -lt $keep.Count; $i++) {
|        if (-not (& $isErr $keep[$i])) { continue }
|        if (& $isWeak $keep[$i]) { $weak = $i } else { $strong = $i }
|    }
|    $first = if ($strong -ge 0) { $strong } else { $weak }
|    if ($first -ge 0) {
|        $wantWeak = ($strong -lt 0)
|        while ($first -gt 0 -and (& $isErr $keep[$first - 1]) -and ($wantWeak -or -not (& $isWeak $keep[$first - 1]))) { $first-- }
|    }
|    $pick = if ($first -ge 0) { @($keep.GetRange($first, [Math]::Min($Max, $keep.Count - $first))) } else { @($keep.GetRange([Math]::Max(0, $keep.Count - $Max), [Math]::Min($Max, $keep.Count))) }
|    $t = ($pick -join "`n")
|    if ($t.Length -gt $MaxChars) { $t = $t.Substring(0, $MaxChars) }
|    $t
|}
|
|function Get-SIErrorRecordSummary {
|    <# PURE. The words of a caught error, never empty: its message, else its exception type + error id + where it was
|       raised (an exception thrown without a message reached Invardia as an empty text -- si-trend x5). #>
|    param([AllowNull()]$ErrorRecord)
|    if ($null -eq $ErrorRecord) { return '' }
|    $ex = if ($ErrorRecord -is [System.Exception]) { $ErrorRecord } elseif ($ErrorRecord.PSObject.Properties['Exception']) { $ErrorRecord.Exception } else { $null }
|    $m = if ($ex) { "$($ex.Message)".Trim() } else { "$ErrorRecord".Trim() }
|    if ($m) { return $m }
|    $parts = New-Object System.Collections.Generic.List[string]
|    if ($ex) { $parts.Add($ex.GetType().FullName) }
|    if ($ErrorRecord.PSObject.Properties['FullyQualifiedErrorId'] -and "$($ErrorRecord.FullyQualifiedErrorId)".Trim()) { $parts.Add("id $($ErrorRecord.FullyQualifiedErrorId)") }
|    if ($ErrorRecord.PSObject.Properties['InvocationInfo'] -and $ErrorRecord.InvocationInfo -and $ErrorRecord.InvocationInfo.ScriptName) { $parts.Add(('at {0}:{1}' -f (Split-Path -Leaf $ErrorRecord.InvocationInfo.ScriptName), $ErrorRecord.InvocationInfo.ScriptLineNumber)) }
|    if (-not $parts.Count) { return 'an error without a message' }
|    'an error without a message (' + ($parts -join ', ') + ')'
|}
|
|function Get-SIErrorClass {
|    <#
|        PURE. The error class of one failure -- exactly one value of Get-SIErrorClasses.
|          -ErrorRecord  an ErrorRecord or an exception (its message, response body, typed body and inner exceptions are
|                        all read -- Get-SIKqlErrorText)
|          -Message      a text (a run-health ErrorMessage, a log line)
|          -ExitReason   the run's ExitReason: 'settings-error' is its own class whatever the text says
|          -Service      a hint when the caller knows which service it called (graph, defender, arm, kv, storage, sql,
|                        ingest, ai) -- used when the text does not name one
|    #>
|    param([AllowNull()]$ErrorRecord, [AllowEmptyString()][AllowNull()][string]$Message, [AllowEmptyString()][string]$ExitReason, [AllowEmptyString()][string]$Service)
|    if ($ExitReason -eq 'settings-error') { return 'settings-error' }
|    if ("$Message" -match '^[a-z0-9][a-z0-9.-]{0,99} refused: ') { return 'guard-refused' }
|    $parts = New-Object System.Collections.Generic.List[string]
|    if ($null -ne $ErrorRecord) { $parts.Add((Get-SIKqlErrorText -ErrorRecord $ErrorRecord)) }
|    if ($Message) { $parts.Add($Message) }
|    $t = ($parts | Where-Object { $_ }) -join ' | '
|    # #702 (1): out of memory ANYWHERE in the text wins over every service / platform word around it (customer B's
|    # "... parameter 'TimeoutSec'. Exception of type 'System.OutOfMemoryException' was thrown" read as platform-timeout)
|    if ((Test-SIOutOfMemoryText $t) -or ($null -ne $ErrorRecord -and (Test-SIOutOfMemoryText $ErrorRecord))) { return 'out-of-memory' }
|    if ([string]::IsNullOrWhiteSpace($t)) { return 'unknown' }
|    # #904: the database is full -- before every service / platform word (its text names SQL and often a timeout)
|    if ((Test-SIDatabaseFullError $t) -or ($null -ne $ErrorRecord -and (Test-SIDatabaseFullError $ErrorRecord))) { return 'database-full' }
|    # 2026-10-29: a temporary Azure SQL error that outlasted SecurityInsight's own retry is TAGGED by the code that retried
|    # it -- its message ends "-- transient-sql" (SI-DataSql.ps1, the pipeline lock); the step's log carries that line, so the
|    # pipeline's report of the step names the platform's class, never a product defect
|    if ($t -match '(?i)--\s*transient-sql\b') { return 'transient-sql' }
|    $svc =Get-SIErrorService -Text $t
|    if (-not $svc -and $Service) { $svc = $Service.ToLowerInvariant() }
|
|    # ---- the run's own configuration ----------------------------------------------------------------------------------
|    if ($t -match '(?i)SecurityInsight Pro: .*settings database|in the settings database are not valid|settings documents could not be prepared') { return 'settings-error' }
|    if ($t -match '(?i)\blicen[cs]e\b.*\b(invalid|not valid|expired|signature verification FAILED|tampered|no entitlement|not readable|could not be read|does not include feature|names no SecurityInsight Pro edition|does not list it)\b|no \.(pimlicense|silicense|aitlicense)|not an AutomateIT licence|signature verification FAILED.*licensing key') { return 'licence-invalid' }
|
|    # ---- identity / sign-in -----------------------------------------------------------------------------------------
|    if ($t -match '(?i)ManagedIdentityCredential|No Managed Identity endpoint|169\.254\.169\.254|IDENTITY_ENDPOINT|\bIMDS\b|MSI endpoint|managed identity.*(unavailable|not available|not found|could not|failed|is not loaded)|identity token helper is not loaded') { return 'mi-unavailable' }
|    if ($t -match "(?i)Login failed for user|Cannot open (server|database) .* requested by the login|\b18456\b|token-identified principal") { return 'sql-login' }
|    if ($t -match "(?i)Cannot (bind|validate) argument (to|on) parameter '(Az)?(ApplicationId|AppId|TenantId|ClientId|CertificateThumbprint|Thumbprint|SubscriptionId|VaultName|WorkspaceId|DcrImmutableId|DceUri|ServicePrincipal\w*)' because it is (an empty string|null)|is not (set|configured)|not found in the configuration|the Pro database is not configured|certificate .* was not found") { return 'config-missing' }
|
|    # ---- ingestion --------------------------------------------------------------------------------------------------
|    if ($t -match '(?i)wrote fewer rows than it carried|fewer rows than (were )?(sent|posted|expected)|short count|rows? (were )?(lost|dropped) (at|during) ingest|accepted \d+ of \d+ rows') { return 'ingest-short-count' }
|
|    # ---- Log Analytics / advanced hunting: the query and the tables -------------------------------------------------
|    # #876: a 'union' leaf says "table expression", a 'where' leaf "table or column expression" -- both: the table is not there
|    if ($t -match "Failed to resolve table (?:or column )?expression named \\?['""]?([A-Za-z0-9_]+)") {
|        $name = $Matches[1]
|        if ($name -match '(?i)_CL$' -or $t -match '(?i)\btable\b.*(could not be found|does not exist)') { return 'table-missing' }
|    }
|    if ($t -match "(?i)\btable\b[^|]{0,120}\b(could not be found|does not exist)|unknown table|PathNotFoundError|not present in this tenant's advanced hunting schema") { return 'table-missing' }
|    foreach ($p in (Get-SIErrorPlatformPrefixesState)) { if ($t -match $p.Pattern) { return $p.Class } }
|    if ($t -match '(?i)Fix syntax errors in your query|Fix semantic errors in your query|SyntaxError|SemanticError|return types are not compatible|\bSEM\d{4}\b|\bSYN\d{4}\b|Expected: .* in query|Failed to resolve (scalar|table or column|table) expression') { return 'kql-query-defect' }
|
|    # ---- throttling -------------------------------------------------------------------------------------------------
|    # ONE decision (Get-SITransientKind): only a real throttling answer is 'throttled'. A Retry-After header alone is not
|    # (a 503 sends one too); SI's own "Microsoft throttled this run" sentence never classifies itself.
|    if ((Get-SITransientKind -Message $t) -eq 'throttled') { return 'throttled' }
|
|    # ---- status codes, by service -----------------------------------------------------------------------------------
|    $code = $null
|    if ($t -match '(?i)\((4\d\d)\)|status code (?:does not indicate success: )?(4\d\d)\b|\b(4\d\d) \((Bad Request|Unauthorized|Forbidden|Not Found|Request Entity Too Large|Conflict)\)|''(BadRequest|Unauthorized|Forbidden|NotFound|RequestEntityTooLarge)''') {
|        $code = @($Matches[1], $Matches[2], $Matches[3], $Matches[5]) | Where-Object { $_ } | Select-Object -First 1
|    }
|    $named = @{ BadRequest = '400'; Unauthorized = '401'; Forbidden = '403'; NotFound = '404'; RequestEntityTooLarge = '413' }
|    if ($code -and $named.ContainsKey($code)) { $code = $named[$code] }
|    $is401 = ($code -eq '401') -or ($t -match '(?i)\bUnauthorized\b|InvalidAuthenticationToken|token is expired|Lifetime validation failed')
|    $is403 = ($code -eq '403') -or ($t -match '(?i)\bForbidden\b|Authorization_RequestDenied|AuthorizationFailed|AuthorizationPermissionMismatch|Insufficient privileges|does not have authorization|does not have (any of )?the required|is not authorized to perform|ForbiddenByRbac|ForbiddenByPolicy|Access denied')
|    if ($svc -eq 'ingest' -and ($code -match '^4\d\d$' -or $is401 -or $is403 -or $t -match '(?i)InvalidTransformOutput|is not associated with DCR|DCE FQDN')) { return 'ingest-4xx' }
|    if ($is401 -or $is403) {
|        switch ($svc) {
|            'graph'    { if ($is401 -and -not $is403) { return 'graph-401' } else { return 'graph-403' } }
|            'defender' { return 'defender-403' }
|            'arm'      { return 'arm-403' }
|            'kv'       { return 'kv-403' }
|            'storage'  { return 'storage-403' }
|            'sql'      { return 'sql-login' }
|            'ai'       { return 'ai-error' }
|            default    { if ($is401 -and -not $is403) { return 'graph-401' } }
|        }
|    }
|
|    # ---- AI ---------------------------------------------------------------------------------------------------------
|    if ($svc -eq 'ai') { return 'ai-error' }
|
|    # ---- the platform -----------------------------------------------------------------------------------------------
|    switch (Get-SITransientKind -Message $t) {
|        'timeout'     { return 'platform-timeout' }
|        'unavailable' { return 'platform-5xx' }
|    }
|    'unknown'
|}
'@ }
$__siSupportFiles['engine/_shared/SI-KqlError.ps1'] = @{ Sha256 = 'ee8dfba0c796cb9c3a24f592a058e3b1223b4edff9a71df30d7bd65465d14221'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- what a failed Log Analytics query actually said (#221).
|
|    WHY. Az.OperationalInsights throws ErrorResponseException whose MESSAGE is only
|    "Operation returned an invalid status code 'BadRequest'". The reason -- e.g. SEM0100 "Failed to resolve table or
|    column expression named 'SI_PublicIP_Profile_CL'" -- is in the response body (Exception.Response.Content /
|    Exception.Body). Measured 2026-10-03 on 3.4.0 (container) and 3.4.1 (the development machine), PS 5.1 and pwsh 7 alike.
|    Readers that classified on the message therefore never recognised a MISSING table: on a fresh install, where a
|    profile or Risk Analysis table does not exist yet, correlation, trend and the close-loop failed outright.
|
|    A missing table is the ONLY error a reader may treat as "no data here yet". Everything else still fails loudly --
|    a throttle or timeout must never pass as an empty table (#132).
|
|    PS 5.1 safe: no ?. / ??.
|#>
|
|function Get-SIKqlErrorText {
|    <# PURE. Every text a Log Analytics query failure carries: the message, the response body, the typed body, inner
|       exceptions and ErrorDetails -- joined, so a caller can classify on what the service really said. #>
|    param([Parameter(Mandatory)][AllowNull()]$ErrorRecord)
|    if ($null -eq $ErrorRecord) { return '' }
|    $parts = New-Object System.Collections.Generic.List[string]
|    $ex = if ($ErrorRecord -is [System.Management.Automation.ErrorRecord]) { $ErrorRecord.Exception } else { $ErrorRecord }
|    if ($ErrorRecord -is [System.Management.Automation.ErrorRecord] -and $ErrorRecord.ErrorDetails -and $ErrorRecord.ErrorDetails.Message) {
|        $parts.Add([string]$ErrorRecord.ErrorDetails.Message)
|    }
|    $depth = 0
|    while ($ex -and $depth -lt 5) {
|        $parts.Add([string]$ex.Message)
|        if ($ex.PSObject.Properties['Response'] -and $ex.Response) {
|            $c = $null
|            if ($ex.Response.PSObject.Properties['Content']) { $c = $ex.Response.Content }
|            if ($c) { $parts.Add([string]$c) }
|        }
|        if ($ex.PSObject.Properties['Body'] -and $ex.Body) {
|            try { $parts.Add((ConvertTo-Json -InputObject $ex.Body -Depth 8 -Compress)) } catch { $parts.Add([string]$ex.Body) }
|        }
|        $ex = $ex.InnerException
|        $depth++
|    }
|    return (($parts | Where-Object { $_ }) -join ' | ')
|}
|
|function Get-SIKqlErrorSummary {
|    <# PURE. ONE log-ready line: the exception message plus the service's own error code(s) and the innermost
|       message, e.g. "Operation returned an invalid status code 'BadRequest' -- SemanticError/SEM0100: 'summarize'
|       operator: Failed to resolve scalar expression named 'AssetName'". Without it a query defect logs only
|       "BadRequest", which says nothing about what to fix. The bare message is kept at the front so classifiers that
|       match on it (BadRequest, TaskCanceledException, 502 ...) see exactly what they saw before. #>
|    param([Parameter(Mandatory)][AllowNull()]$ErrorRecord)
|    if ($null -eq $ErrorRecord) { return '' }
|    $ex = if ($ErrorRecord -is [System.Management.Automation.ErrorRecord]) { $ErrorRecord.Exception } else { $ErrorRecord }
|    $base = if ($ex -and $ex.PSObject.Properties['Message']) { [string]$ex.Message } else { [string]$ex }
|    $text = Get-SIKqlErrorText -ErrorRecord $ErrorRecord
|    if (-not $text) { return $base }
|    # The Log Analytics body nests the reason: error -> innererror (SemanticError / SyntaxError) -> innererror
|    # (SEM0100 ...). Collect the innererror chain of the first body found; the deepest message is the useful one.
|    $rx = '"innererror"\s*:\s*\{\s*"code"\s*:\s*"([^"]*)"\s*,\s*"message"\s*:\s*"((?:[^"\\]|\\.)*)"'
|    $ms = [regex]::Matches($text, $rx)
|    if ($ms.Count -eq 0) { return $base }
|    $codes = New-Object System.Collections.Generic.List[string]
|    $msg = ''
|    foreach ($m in $ms) {
|        $c = $m.Groups[1].Value
|        if ($codes.Contains($c)) { break }   # a second copy of the same body (typed body / ErrorDetails) starts here
|        $codes.Add($c)
|        $msg = $m.Groups[2].Value
|    }
|    try { $msg = [regex]::Unescape($msg) } catch { }
|    $detail = ('{0}: {1}' -f ($codes -join '/'), $msg)
|    if ($base -and $base.Contains($msg)) { return $base }
|    if (-not $base) { return $detail }
|    return ('{0} -- {1}' -f $base, $detail)
|}
|
|function Test-SIKqlTableMissing {
|    <# PURE. True only when the failure says THIS table does not exist in the workspace. #>
|    param([Parameter(Mandatory)][AllowNull()]$ErrorRecord, [Parameter(Mandatory)][string]$TableName)
|    $t = Get-SIKqlErrorText -ErrorRecord $ErrorRecord
|    if (-not $t) { return $false }
|    $name = [regex]::Escape($TableName)
|    # #876: a 'union' leaf says "table expression", a 'where' leaf "table or column expression" -- both: the table is not there
|    if ($t -match ("Failed to resolve table (?:or column )?expression named \\?['""]?{0}" -f $name)) { return $true }
|    if ($t -match $name -and $t -match '(?i)SEM0100|could not be found|does not exist|unknown table') { return $true }
|    return $false
|}
'@ }
$__siSupportFiles['auth/SI-ManagedIdentity.ps1'] = @{ Sha256 = '8198e8e891fb59de6e58fe9f8b08fe7f3f838586096d36758b85aa0e118f6673'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- sign in with a MANAGED IDENTITY: a container job's (#209), an Azure VM's or an Azure Arc
|    server's (#222).
|
|    WHY. An engine container could only sign in with an SPN client SECRET. Internal installs are certificate
|    only, and Pro is container only, so a certificate-only customer could not run Pro at all. PIM4EntraPS's
|    containers sign in as the job's managed identity; this copies that (PIM: Get-PimManagedIdentityToken).
|    #222 (operator 2026-10-03): the managed identity is the DEFAULT everywhere; an SPN stays supported.
|
|    THE ONE SWITCH. A run uses the managed identity when $global:SI_UseManagedIdentity = $true.
|        $global:SI_UAMI_ClientId = '<client id>'   optional: a USER-assigned identity; empty = the host's
|                                                    system-assigned identity
|    Who sets it: the container entry points (when the job has an identity endpoint), and on a VM the sign-in
|    decision in the config loader (auth/SI-AuthMethod.ps1). When it is off, every function below either is
|    never called or returns "not mine" -- the secret and certificate paths are exactly what they were.
|    The host decides the endpoint (Get-SIManagedIdentityHost): container IDENTITY_ENDPOINT + IDENTITY_HEADER;
|    Azure Arc IDENTITY_ENDPOINT + IMDS_ENDPOINT (401 challenge file); otherwise the Azure VM endpoint.
|
|    Log ingestion keeps its existing switch ($global:SI_PreferUami + SI_UAMI_ClientId -> -UseManagedIdentity on
|    SI's REST ingestion, which mints the token here); the container sets that from the same decision. No second
|    identity switch.
|
|    PS 5.1 safe: no ?. / ??.
|#>
|
|# Azure access: plain REST, no PowerShell modules (engine/_shared/SI-AzRest.ps1).
|if (-not (Get-Command -Name Invoke-SIArm -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot '../engine/_shared/SI-AzRest.ps1') }
|
|$__siFindCert = Join-Path $PSScriptRoot 'Find-SICertificate.ps1'
|if ((Test-Path -LiteralPath $__siFindCert) -and -not (Get-Command Get-SICertificateFromStore -ErrorAction SilentlyContinue)) { . $__siFindCert }
|
|if (-not (Get-Variable -Name SIManagedIdentityTokenCache -Scope Script -ErrorAction SilentlyContinue)) {
|    $script:SIManagedIdentityTokenCache = @{}   # '<clientId>|<resource>' -> @{ Token; ExpiresAt }
|}
|
|function Test-SIUseManagedIdentity {
|    <# THE switch: this run signs in as a managed identity (a container job's, an Azure VM's or an Azure Arc
|       server's -- #222). The client id is optional: empty = the host's SYSTEM-assigned identity. #>
|    return [bool]$global:SI_UseManagedIdentity
|}
|
|function Get-SIManagedIdentityHost {
|    <#
|        PURE (reads env only). Which managed-identity endpoint this host has (#222):
|          Container -- Azure Container Apps / App Service: IDENTITY_ENDPOINT + IDENTITY_HEADER
|          Arc       -- an Azure Arc-enabled server: IDENTITY_ENDPOINT + IMDS_ENDPOINT, no IDENTITY_HEADER (the Arc
|                       agent sets both machine-wide); the token needs a challenge-file handshake
|          AzureVm   -- an Azure VM (and anything else): the instance metadata endpoint 169.254.169.254
|    #>
|    param([scriptblock]$GetEnv)
|    if (-not $GetEnv) { $GetEnv = { param($n) [Environment]::GetEnvironmentVariable($n) } }
|    $ep = [string](& $GetEnv 'IDENTITY_ENDPOINT'); $hd = [string](& $GetEnv 'IDENTITY_HEADER'); $imds = [string](& $GetEnv 'IMDS_ENDPOINT')
|    if ($ep -and $hd) { return 'Container' }
|    if ($ep -and $imds) { return 'Arc' }
|    return 'AzureVm'
|}
|
|function Get-SIManagedIdentityToken {
|    <#
|        A token for -Resource as this host's managed identity (#209 container, #222 Azure VM + Azure Arc):
|          Container -- IDENTITY_ENDPOINT + X-IDENTITY-HEADER, api-version 2019-08-01, client_id when known
|          AzureVm   -- http://169.254.169.254/metadata/identity/oauth2/token, Metadata: true, client_id when known
|          Arc       -- IDENTITY_ENDPOINT (api-version 2020-06-01, Metadata: true): the first call answers 401 with
|                       'WWW-Authenticate: Basic realm=<file>'; the file's content is the secret for the second call.
|                       Reading it needs local Administrators or the 'Hybrid agent extension applications' group. Arc
|                       has the SYSTEM-assigned identity only, so no client_id.
|
|        TRAP: THE client_id IS NOT OPTIONAL IN PRACTICE for a user-assigned identity. PIM4EntraPS measured it: with a
|        user-assigned identity only, the endpoint has nothing to default to and the failure surfaces far away as
|        "Login failed" / 401. So it is always sent when known.
|
|        Cached per identity + resource until 5 minutes before the token's own expiry. -Invoke is a test seam:
|        { param($Uri, $Headers) } returning the endpoint's response (Arc: the @{Status;Body;WwwAuthenticate} shape).
|        -ReadFile is a test seam for the Arc challenge file.
|    #>
|    param(
|        [Parameter(Mandatory)][string]$Resource,
|        [string]$ClientId,
|        [switch]$ForceRefresh,
|        [scriptblock]$Invoke,
|        [scriptblock]$ReadFile
|    )
|    # A guided install's own sign-in wins (live 2026-10-06, an AzContext install on an Azure VM got the VM's IMDS token for
|    # SQL): while $global:SI_InstallTokenProvider is set, the token comes from it and NO identity endpoint is called.
|    $installProvider = Get-Variable -Scope Global -Name SI_InstallTokenProvider -ValueOnly -ErrorAction Ignore
|    # Re-entry = the install's sign-in itself IS this host's managed identity (sign-in mode ManagedIdentity): then, and only
|    # then, the identity endpoint below answers.
|    if (($installProvider -is [scriptblock]) -and -not $global:SI_InstallTokenProviderBusy) {
|        $global:SI_InstallTokenProviderBusy = $true
|        try { $pt = [string](& $installProvider $Resource) } finally { $global:SI_InstallTokenProviderBusy = $false }
|        if ([string]::IsNullOrWhiteSpace($pt)) { throw ("the install's sign-in returned no token for '{0}'." -f $Resource) }
|        return $pt
|    }
|    # SELF-CONTAINED on purpose: it is published to the global scope and may run where this file's other functions are
|    # not visible. The host rule is Get-SIManagedIdentityHost's, repeated here.
|    $endpoint = [Environment]::GetEnvironmentVariable('IDENTITY_ENDPOINT')
|    $header   = [Environment]::GetEnvironmentVariable('IDENTITY_HEADER')
|    $imdsEp   = [Environment]::GetEnvironmentVariable('IMDS_ENDPOINT')
|    $hostKind = if ($endpoint -and $header) { 'Container' } elseif ($endpoint -and $imdsEp) { 'Arc' } else { 'AzureVm' }
|    $arcGet = {
|        param([string]$U, [hashtable]$H)
|        $req = [System.Net.HttpWebRequest]::Create($U)
|        $req.Method = 'GET'; $req.Timeout = 60000
|        foreach ($k in $H.Keys) { if ($k -eq 'Authorization') { $req.Headers['Authorization'] = [string]$H[$k] } else { $req.Headers.Add($k, [string]$H[$k]) } }
|        try { $r = $req.GetResponse() }
|        catch [System.Net.WebException] { $r = $_.Exception.Response; if (-not $r) { throw } }
|        try {
|            $sr = New-Object System.IO.StreamReader($r.GetResponseStream()); $b = $sr.ReadToEnd(); $sr.Close()
|            [pscustomobject]@{ Status = [int]$r.StatusCode; Body = $b; WwwAuthenticate = [string]$r.Headers['WWW-Authenticate'] }
|        } finally { $r.Close() }
|    }
|    if ([string]::IsNullOrWhiteSpace($ClientId)) { $ClientId = [string]$global:SI_UAMI_ClientId }
|    # The cache is created HERE, not only when this file loads: when this function runs from another scope, `$script:` is
|    # that scope and the file-level cache does not exist.
|    # Measured live 2026-10-02 (first container run on the identity): "You cannot call a method on a null-valued
|    # expression" on every token, and every Log Analytics post failed.
|    if ($null -eq $script:SIManagedIdentityTokenCache) { $script:SIManagedIdentityTokenCache = @{} }
|    $res = ($Resource -replace '/\.default$', '')
|    $key = '{0}|{1}' -f $ClientId, $res
|    if (-not $ForceRefresh -and $script:SIManagedIdentityTokenCache.ContainsKey($key)) {
|        $c = $script:SIManagedIdentityTokenCache[$key]
|        if ($c.ExpiresAt -gt [datetime]::UtcNow) { return $c.Token }
|    }
|
|    $resp = $null
|    switch ($hostKind) {
|        'Container' {
|            $uri = '{0}?resource={1}&api-version=2019-08-01' -f $endpoint, [uri]::EscapeDataString($res)
|            if (-not [string]::IsNullOrWhiteSpace($ClientId)) { $uri += '&client_id=' + [uri]::EscapeDataString($ClientId) }
|            $headers = @{ 'X-IDENTITY-HEADER' = $header }
|            $resp = if ($Invoke) { & $Invoke $uri $headers }
|                    else { Invoke-RestMethod -Method Get -Uri $uri -Headers $headers -TimeoutSec 60 }
|        }
|        'AzureVm' {
|            $uri = 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource={0}' -f [uri]::EscapeDataString($res)
|            if (-not [string]::IsNullOrWhiteSpace($ClientId)) { $uri += '&client_id=' + [uri]::EscapeDataString($ClientId) }
|            $headers = @{ 'Metadata' = 'true' }
|            $resp = if ($Invoke) { & $Invoke $uri $headers }
|                    else { Invoke-RestMethod -Method Get -Uri $uri -Headers $headers -TimeoutSec 60 }
|        }
|        'Arc' {
|            $uri = '{0}?api-version=2020-06-01&resource={1}' -f $endpoint, [uri]::EscapeDataString($res)
|            $first = if ($Invoke) { & $Invoke $uri @{ 'Metadata' = 'true' } } else { & $arcGet $uri @{ 'Metadata' = 'true' } }
|            if ([int]$first.Status -ne 401 -or [string]$first.WwwAuthenticate -notmatch '(?i)realm=(.+)$') {
|                throw ("managed identity (Azure Arc): expected a 401 challenge from {0}, got {1}. Is the Arc agent running?" -f $endpoint, $first.Status)
|            }
|            $keyFile = $Matches[1].Trim().Trim('"')
|            $secret = $null
|            try { $secret = if ($ReadFile) { & $ReadFile $keyFile } else { [System.IO.File]::ReadAllText($keyFile) } }
|            catch { throw ("managed identity (Azure Arc): cannot read the challenge file {0} -- the run must be a local Administrator or in the 'Hybrid agent extension applications' group. {1}" -f $keyFile, $_.Exception.Message) }
|            $second = if ($Invoke) { & $Invoke $uri @{ 'Metadata' = 'true'; 'Authorization' = ('Basic ' + $secret) } }
|                      else { & $arcGet $uri @{ 'Metadata' = 'true'; 'Authorization' = ('Basic ' + $secret) } }
|            if ([int]$second.Status -ne 200) { throw ("managed identity (Azure Arc): the identity endpoint refused the token request ({0})." -f $second.Status) }
|            $resp = $second.Body | ConvertFrom-Json
|        }
|    }
|    $token = [string]$resp.access_token
|    if ([string]::IsNullOrWhiteSpace($token)) {
|        throw ("managed identity ({2}): the identity endpoint returned no token for '{0}' (client id {1}). Is that identity assigned to this host / job?" -f $res, $ClientId, $hostKind)
|    }
|
|    $expiresAt = [datetime]::UtcNow.AddMinutes(50)
|    $epoch = 0L
|    if ([long]::TryParse([string]$resp.expires_on, [ref]$epoch) -and $epoch -gt 0) {
|        $expiresAt = [DateTimeOffset]::FromUnixTimeSeconds($epoch).UtcDateTime.AddMinutes(-5)
|    } else {
|        $secs = 0
|        if ([int]::TryParse([string]$resp.expires_in, [ref]$secs) -and $secs -gt 600) { $expiresAt = [datetime]::UtcNow.AddSeconds($secs - 300) }
|    }
|    $script:SIManagedIdentityTokenCache[$key] = @{ Token = $token; ExpiresAt = $expiresAt }
|    # #232 -- the licence is checked against the tenant the identity REALLY lives in. A managed identity's token always
|    # comes from its home tenant, whatever the configuration claims, so its 'tid' claim is the proof; a configured tenant
|    # id is not (a copied licence plus an edited config would otherwise pass). Recorded from every real token.
|    try {
|        $seg = $token.Split('.')
|        if ($seg.Count -ge 2) {
|            $p = $seg[1].Replace('-', '+').Replace('_', '/'); while ($p.Length % 4) { $p += '=' }
|            $tid = [string](([System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p))) | ConvertFrom-Json).tid
|            if ($tid -match '^[0-9a-fA-F-]{36}$') { $global:SI_IdentityTokenTenantId = $tid.ToLowerInvariant() }
|        }
|    } catch { }
|    try { [System.Console]::Out.WriteLine(("  [mi] token for {0} via the {2} identity endpoint (len {1})" -f $res, $token.Length, $hostKind)) } catch { }
|    return $token
|}
|
|function Get-SIAccessToken {
|    <#
|        "A token for resource X as the identity this run uses." The managed identity when the switch is on;
|        otherwise the run's own sign-in (Get-SIAzAccessToken, over REST).
|    #>
|    param([Parameter(Mandatory)][string]$Resource, [switch]$ForceRefresh)
|    if (Test-SIUseManagedIdentity) { return (Get-SIManagedIdentityToken -Resource $Resource -ForceRefresh:$ForceRefresh) }
|    $t = Get-SIAzAccessToken -ResourceUrl $Resource -ErrorAction Stop
|    if ($t.Token -is [System.Security.SecureString]) { return [System.Net.NetworkCredential]::new('', $t.Token).Password }
|    return [string]$t.Token
|}
'@ }
$__siSupportFiles['engine/_shared/SI-LicenceRequest.ps1'] = @{ Sha256 = 'fe3f7ca1e8a8ffde8aec12b715287f3797cc760f94aeea7f0ffc084405ec0ed0'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- THE INSTALL REQUESTS AND RENEWS ITS OWN LICENCE (#239).
|
|    The contract is Invardia's (licence requests, owner GO 2026-10-03). Three steps, run by the updater job on each
|    update run (container/updater/_shared/SI-UpdaterLicence.ps1) and by setup/Request-SILicense.ps1 by hand:
|
|      1. KNOCK  -- when there is no valid licence for THIS tenant, or the one installed ends within 30 days:
|                   POST <base>/api/licence-requests  {product, version, tenantId, installId, edition?, contactEmail?,
|                   currentLicenceId?, currentValidTo?}  ->  202 {requestId, pullToken, status, pollAfterSeconds}.
|                   The pull token is kept in the install's Key Vault (SI-LicenceRequest-PullToken), never printed.
|                   A repeat knock returns the same request with a NEW token, which overwrites the stored one.
|      2. PULL   -- each run, never faster than pollAfterSeconds: POST <base>/api/licence-requests/pull with the header
|                   X-Invardia-Pull-Token and the JSON body {} -> {status: Pending | Rejected | Approved, licence?}.
|                   401 = the token is unknown or expired -> knock again. A token older than 30 days is not used.
|      3. VERIFY offline, then INSTALL -- the SHA-256 of the file, the signature against the trusted signers (the
|                   framework verifier, engine/_shared/AitLicense.ps1), the REAL tenant among its tenantIds, valid dates,
|                   product securityinsight and features SecurityInsight has. Only then setup/Set-SILicense.ps1 writes
|                   SI-License (it verifies again and reads it back), and the cycle reads it back once more.
|
|    🔒 THE TENANT IS THE TOKEN'S, NEVER THE CONFIG'S. The tenant sent and checked is the 'tid' of the identity's own
|    access token (a managed identity: $global:SI_IdentityTokenTenantId, recorded by the managed identity token helper in auth/; an SPN:
|    the tid of its token). A tenant that cannot be proven is not guessed: nothing is sent.
|
|    Answers that are not a licence: Rejected is stored with its reason and shown to the admin; it is NOT asked again
|    automatically for 7 days (Request-SILicense.ps1 -Force asks at once). 422 = Invardia refused the request body: the
|    fields are reported and the request is not repeated for a day. 429 = wait at least Retry-After. A network failure is
|    a warning; it never fails the run that called this.
|
|    The state (no token) is kept as the Key Vault secret SI-LicenceRequest-State and, on a Pro install, mirrored into the
|    Pro database (cfg.InstallState 'LicenceRequest') for the web app. The install id is SI-InstallId, created once.
|
|    Every call that leaves the process goes through -Seams, so the contract test runs offline. PS 5.1 safe.
|#>
|
|# Azure access: plain REST, no PowerShell modules (engine/_shared/SI-AzRest.ps1).
|if (-not (Get-Command -Name Invoke-SIArm -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot 'SI-AzRest.ps1') }
|# #517: the re-issued licence marker the engine records (Read-SILicenceSupersededMark -- the updater's SupersededBy seam)
|if (-not (Get-Command -Name Read-SILicenceSupersededMark -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot 'SI-LicenceSuperseded.ps1') }
|# Invardia S16: the install's lasting id (SI-InstallId) as X-Invardia-Install-Id on the knock
|if (-not (Get-Command -Name ConvertTo-SIInvardiaInstallId -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot 'SI-InvardiaInstallId.ps1') }
|
|# NO Set-StrictMode HERE -- a dot-sourced file that sets it leaks into the caller's scope.
|
|$script:SILicenceRequestProduct      = 'securityinsight'
|$script:SILicenceRequestDefaultBase  = 'https://invardia.com'
|$script:SILicenceRequestSecretState  = 'SI-LicenceRequest-State'
|$script:SILicenceRequestSecretToken  = 'SI-LicenceRequest-PullToken'
|$script:SILicenceRequestSecretId     = 'SI-InstallId'
|$script:SILicenceRequestSecretLic    = 'SI-License'
|$script:SILicenceRequestTokenHeader  = 'X-Invardia-Pull-Token'
|$script:SILicenceRequestRenewDays    = 30      # knock when the licence ends within this many days
|$script:SILicenceRequestRejectDays   = 7       # after a rejection, ask again only after this many days (or -Force)
|$script:SILicenceRequestTokenDays    = 30      # a pull token lives this long
|$script:SILicenceRequestPollSeconds  = 1800    # when Invardia sends no pollAfterSeconds (it sends 1800)
|$script:SILicenceRequestInvalidHours = 24      # after a 422, the request is not repeated for this long
|$script:SILicenceRequestStates       = @('none', 'requested', 'pending', 'approved', 'rejected')
|
|# The licence verifier and the feature catalog (Get-SILicense, Test-SILicenseForInstall, Resolve-AitLicenseStatus).
|if (-not (Get-Command -Name Test-SILicenseForInstall -ErrorAction SilentlyContinue)) {
|    $siLrCatalog = [IO.Path]::Combine((Split-Path -Parent $PSScriptRoot), 'SI-FeatureCatalog.ps1')
|    if (Test-Path -LiteralPath $siLrCatalog) { . $siLrCatalog }
|}
|
|# =====================================================================================================================
|#  Pure helpers
|# =====================================================================================================================
|function Get-SILicenceRequestBaseUrl {
|    <#
|        Where Invardia is: -BaseUrl, else $global:SI_LicenseRequest_BaseUrl, else $env:SI_LICENSE_REQUEST_BASE_URL, else
|        https://invardia.com. HTTPS only (the pull token travels in a header). No trailing slash.
|        The install key and the pull token go to Invardia's own address only: a SETTING (the global, which a settings row can
|        set) that is not https://...invardia.com is left out and said -- the job's own value or the default applies.
|    #>
|    param([string]$BaseUrl)
|    $fromSetting = "$(Get-Variable -Name SI_LicenseRequest_BaseUrl -Scope Global -ValueOnly -ErrorAction SilentlyContinue)".Trim()
|    if ($fromSetting) {
|        if (-not (Get-Command -Name Test-SITelemetryEndpointHost -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot 'SI-OutboundTrust.ps1') }
|        $hw = Test-SITelemetryEndpointHost -Endpoint $fromSetting
|        if ($hw) { Write-Warning ("[licence-request] SI_LicenseRequest_BaseUrl is not used: {0} -- the licence request goes to Invardia's own address" -f $hw); $fromSetting = '' }
|    }
|    $u = @($BaseUrl, $fromSetting, [string]$env:SI_LICENSE_REQUEST_BASE_URL) | Where-Object { "$_".Trim() } | Select-Object -First 1
|    if (-not $u) { $u = $script:SILicenceRequestDefaultBase }
|    $u = "$u".Trim().TrimEnd('/')
|    if ($u -notmatch '^https://[^/\s]+') { throw ("the licence request address must be an https:// URL, not '{0}'" -f $u) }
|    $u
|}
|
|function Get-SILicenceRequestTenantFromToken {
|    <# The 'tid' claim of an access token (JWT), lower-case; $null when it has none or is not a token. Never prints it. #>
|    param([AllowNull()][string]$AccessToken)
|    if ([string]::IsNullOrWhiteSpace($AccessToken)) { return $null }
|    try {
|        $seg = $AccessToken.Split('.')
|        if ($seg.Count -lt 2) { return $null }
|        $p = $seg[1].Replace('-', '+').Replace('_', '/'); while ($p.Length % 4) { $p += '=' }
|        $tid = [string](([System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p))) | ConvertFrom-Json).tid
|        if ($tid -match '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$') { return $tid.ToLowerInvariant() }
|    } catch { }
|    return $null
|}
|
|function Test-SILicenceRequestTenantProven {
|    param([AllowNull()][string]$TenantId)
|    return ("$TenantId" -match '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$')
|}
|
|function Test-SILicenceRequestNeeded {
|    <#
|        PURE. Should the install ask for a licence? Yes when it has no valid licence FOR THIS TENANT, or the licence ends
|        within 30 days: (validTo as a UTC date) - (today, UTC) <= 30. Returns @{ Needed; Reason; ValidTo; LicenceId; DaysLeft }.
|    #>
|    param([AllowNull()][object]$License, [AllowNull()][string]$TenantId, [Parameter(Mandatory)][datetime]$NowUtc,
|          # #517 (framework §12.6b): the newest licence Invardia named when it answered that the installed one was re-issued --
|          # a GUID other than the installed licence's id makes the install ask now (Superseded = $true)
|          [AllowNull()][AllowEmptyString()][string]$SupersededBy)
|    $sup = "$SupersededBy".Trim().ToLowerInvariant()
|    if ($sup -notmatch '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$') { $sup = '' }
|    $out = { param($n, $why, $to, $id, $d, $s) [pscustomobject]@{ Needed = [bool]$n; Reason = $why; ValidTo = $to; LicenceId = $id; DaysLeft = $d; Superseded = [bool]$s } }
|    if ($null -eq $License) { return (& $out $true 'there is no licence' $null '' $null) }
|    $st = "$($License.Status)"
|    $id = "$($License.LicenseId)"
|    $to = $null
|    if ($License.ValidTo) { try { $to = ([datetime]$License.ValidTo).Date } catch { $to = $null } }
|    if ($st -in @('Missing', 'Invalid', 'Expired')) { return (& $out $true ("there is no valid licence ({0})" -f $st) $to $id $null) }
|    $ids = @($License.TenantIds | Where-Object { $_ } | ForEach-Object { "$_".Trim().ToLowerInvariant() })
|    if (-not $ids.Count -or $ids -notcontains "$TenantId".Trim().ToLowerInvariant()) {
|        return (& $out $true 'the licence installed is not for this tenant' $to $id $null)
|    }
|    if ($null -eq $to) { return (& $out $true 'the licence has no end date' $null $id $null) }
|    $days = [int]($to - $NowUtc.ToUniversalTime().Date).TotalDays
|    if ($sup -and $sup -ne "$id".Trim().ToLowerInvariant()) {
|        return (& $out $true ("Invardia has issued a newer licence for this install ({0})" -f $sup) $to $id $days $true)
|    }
|    if ($st -eq 'Grace') { return (& $out $true ("the licence ended {0} and is in its grace period" -f $to.ToString('yyyy-MM-dd')) $to $id $days) }
|    if ($days -le $script:SILicenceRequestRenewDays) {
|        return (& $out $true $(if ($days -lt 0) { "the licence ended {0}" -f $to.ToString('yyyy-MM-dd') } else { "the licence ends in {0} day(s)" -f $days }) $to $id $days)
|    }
|    & $out $false ("the licence is valid until {0}" -f $to.ToString('yyyy-MM-dd')) $to $id $days
|}
|
|function New-SILicenceRequestBody {
|    <#
|        PURE. The knock's JSON body. Field names are the contract's, in its order; an optional field is sent only when it
|        has a value (contactEmail only when configured, the current licence only when there is one).
|    #>
|    param(
|        [Parameter(Mandatory)][string]$Version,
|        [Parameter(Mandatory)][string]$TenantId,
|        [Parameter(Mandatory)][string]$InstallId,
|        [string]$Edition,
|        [string]$ContactEmail,
|        [string]$CurrentLicenceId,
|        [AllowNull()][object]$CurrentValidTo,
|        # the SHA-256 of the licence the install holds (Invardia delivers a renewal only to a knock that proves it holds the
|        # tenant's licence: its id, this hash, or a valid install key in the header). 64 hex characters, else not sent.
|        [string]$CurrentLicenceSha256
|    )
|    $b = [ordered]@{ product = $script:SILicenceRequestProduct; version = $Version; tenantId = $TenantId.ToLowerInvariant(); installId = $InstallId }
|    if ("$Edition".Trim())          { $b.edition = "$Edition".Trim() }
|    if ("$ContactEmail".Trim())     { $b.contactEmail = "$ContactEmail".Trim() }
|    if ("$CurrentLicenceId".Trim()) { $b.currentLicenceId = "$CurrentLicenceId".Trim() }
|    if ("$CurrentLicenceSha256".Trim() -match '^[0-9a-fA-F]{64}$') { $b.currentLicenceSha256 = "$CurrentLicenceSha256".Trim().ToLowerInvariant() }
|    if ($null -ne $CurrentValidTo -and "$CurrentValidTo".Trim()) {
|        $b.currentValidTo = ([datetime]$CurrentValidTo).ToString('yyyy-MM-dd', [Globalization.CultureInfo]::InvariantCulture)
|    }
|    $b | ConvertTo-Json -Compress
|}
|
|function Get-SILicenceRequestSha256 {
|    param([Parameter(Mandatory)][byte[]]$Bytes)
|    $h = [System.Security.Cryptography.SHA256]::Create()
|    try { return (($h.ComputeHash($Bytes) | ForEach-Object { $_.ToString('x2') }) -join '') } finally { $h.Dispose() }
|}
|
|function Test-SILicenceRequestFile {
|    <#
|        OFFLINE verification of the licence Invardia handed back, BEFORE anything is installed:
|          * the SHA-256 of the decoded bytes equals 'sha256';
|          * the signature verifies against the trusted signers (the framework verifier);
|          * the dates make it valid today;
|          * the REAL tenant is one of its tenantIds;
|          * the product is securityinsight;
|          * every feature it grants is one SecurityInsight has.
|        Returns @{ Ok; Problems; License; Text }. Never throws.
|    #>
|    param(
|        [Parameter(Mandatory)][AllowNull()][object]$Licence,
|        [AllowNull()][string]$TenantId,
|        [AllowNull()][string[]]$TrustedCertsB64,
|        [AllowNull()][object]$Now
|    )
|    $problems = New-Object System.Collections.Generic.List[string]
|    $res = { param($lic, $text) [pscustomobject]@{ Ok = ($problems.Count -eq 0); Problems = $problems.ToArray(); License = $lic; Text = $text } }
|    if (-not (Test-SILicenceRequestTenantProven $TenantId)) { $problems.Add('the tenant this install runs in is not proven') ; return (& $res $null $null) }
|    if ($null -eq $Licence -or -not "$($Licence.contentBase64)".Trim()) { $problems.Add('the answer carries no licence file'); return (& $res $null $null) }
|    $bytes = $null
|    try { $bytes = [Convert]::FromBase64String("$($Licence.contentBase64)".Trim()) } catch { $problems.Add('the licence file is not base64'); return (& $res $null $null) }
|    $sha = Get-SILicenceRequestSha256 -Bytes $bytes
|    if ($sha -ne "$($Licence.sha256)".Trim().ToLowerInvariant()) {
|        $problems.Add(("the licence file does not match its SHA-256 (file {0}, stated {1})" -f $sha.Substring(0, 12), $(if ("$($Licence.sha256)".Length -ge 12) { "$($Licence.sha256)".Substring(0, 12) } else { "'$($Licence.sha256)'" })))
|        return (& $res $null $null)
|    }
|    $text = [System.Text.Encoding]::UTF8.GetString($bytes).TrimStart([char]0xFEFF).Trim()
|    $doc = $null
|    try { $doc = $text | ConvertFrom-Json -ErrorAction Stop } catch { $doc = $null }
|    if ($null -eq $doc) { $problems.Add('the licence file is not licence JSON'); return (& $res $null $text) }
|    if (-not (Get-Command -Name Resolve-AitLicenseStatus -ErrorAction SilentlyContinue)) { $problems.Add('the licence verifier is not installed'); return (& $res $null $text) }
|    $lic = Resolve-AitLicenseStatus -Document $doc -TrustedCertsB64 $TrustedCertsB64 -Now $Now
|    if ("$($lic.Status)" -eq 'Invalid') { $problems.Add(("the licence does not verify: {0}" -f $lic.Reason)); return (& $res $lic $text) }
|    if ("$($lic.Status)" -ne 'Valid')   { $problems.Add(("the licence dates are not valid today: {0} ({1})" -f $lic.Status, $lic.Reason)) }
|    $ids = @($lic.TenantIds | Where-Object { $_ } | ForEach-Object { "$_".Trim().ToLowerInvariant() })
|    if ($ids -notcontains $TenantId.ToLowerInvariant()) {
|        $problems.Add(("the licence is for tenant(s) {0}, not for this tenant {1}" -f $(if ($ids.Count) { $ids -join ', ' } else { 'none' }), $TenantId))
|    }
|    # The product: the signed payload's when it says one, else the file's own field. Never absent.
|    $prod = ''
|    try { $p = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("$($doc.payloadB64)")) | ConvertFrom-Json; if ($p.PSObject.Properties['product']) { $prod = "$($p.product)" } } catch { }
|    if (-not $prod -and $doc.PSObject.Properties['product']) { $prod = "$($doc.product)" }
|    if (($prod -replace '[^A-Za-z]', '').ToLowerInvariant() -ne $script:SILicenceRequestProduct) {
|        $problems.Add(("the licence is for product '{0}', not SecurityInsight" -f $prod))
|    }
|    if (Get-Command -Name Test-SILicenseForInstall -ErrorAction SilentlyContinue) {
|        $known = @(); if (Get-Command -Name Get-SIFeatureCatalog -ErrorAction SilentlyContinue) { $known = @(Get-SIFeatureCatalog | ForEach-Object { $_.Name }) }
|        $chk = Test-SILicenseForInstall -License $lic -KnownFeatures $known -TenantId $TenantId
|        foreach ($x in @($chk.Problems)) { if ($x -notmatch '^(the licence does not verify|it is bound to tenant)') { $problems.Add($x) } }
|    }
|    & $res $lic $text
|}
|
|# =====================================================================================================================
|#  State (Key Vault, no token) and its mirror
|# =====================================================================================================================
|function ConvertTo-SILicenceRequestUtc {
|    param([AllowNull()]$Value)
|    if ($null -eq $Value -or -not "$Value".Trim()) { return $null }
|    if ($Value -is [datetime]) { return $Value.ToUniversalTime() }
|    $d = [datetime]::MinValue
|    if ([datetime]::TryParse("$Value", [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]'AdjustToUniversal, AssumeUniversal', [ref]$d)) { return $d }
|    $null
|}
|
|function ConvertFrom-SILicenceRequestState {
|    <# The stored state (JSON) as an ordered hashtable with every field; an unreadable state starts empty. #>
|    param([AllowNull()][string]$Json)
|    $s = [ordered]@{ status = 'none'; requestId = ''; requestedUtc = $null; nextPollUtc = $null; nextKnockUtc = $null; pollAfterSeconds = 0
|                     lastCheckUtc = $null; validTo = ''; licenceId = ''; reason = ''; rejectedUtc = $null; lastError = ''; lastResult = ''
|                     # #517: the re-issued licence id already asked for (each one is asked for once)
|                     supersededHandled = '' }
|    if ([string]::IsNullOrWhiteSpace($Json)) { return $s }
|    try { $o = $Json | ConvertFrom-Json -ErrorAction Stop } catch { return $s }
|    foreach ($k in @($s.Keys)) {
|        if (-not $o.PSObject.Properties[$k]) { continue }
|        $v = $o.$k
|        if ($k -like '*Utc') { $s[$k] = ConvertTo-SILicenceRequestUtc $v }
|        elseif ($k -eq 'pollAfterSeconds') { $n = 0; if ([int]::TryParse("$v", [ref]$n)) { $s[$k] = $n } }
|        else { $s[$k] = $(if ($null -eq $v) { '' } else { "$v" }) }
|    }
|    if ($script:SILicenceRequestStates -notcontains $s.status) { $s.status = 'none' }
|    $s
|}
|
|function ConvertTo-SILicenceRequestStateJson {
|    param([Parameter(Mandatory)][System.Collections.IDictionary]$State, [switch]$Compact)
|    $o = [ordered]@{}
|    foreach ($k in $State.Keys) {
|        $v = $State[$k]
|        if ($v -is [datetime]) { $v = $v.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture) }
|        $o[$k] = $v
|    }
|    if ($Compact) {
|        # cfg.InstallState.Value is NVARCHAR(400): the fields the web app shows, with the free text shortened.
|        $short = { param($t) $t = "$t"; if ($t.Length -gt 90) { $t.Substring(0, 87) + '...' } else { $t } }
|        $c = [ordered]@{ status = $o.status; requestedUtc = $o.requestedUtc; nextPollUtc = $o.nextPollUtc; lastCheckUtc = $o.lastCheckUtc
|                         validTo = $o.validTo; reason = (& $short $o.reason); lastError = (& $short $o.lastError) }
|        return ($c | ConvertTo-Json -Compress)
|    }
|    $o | ConvertTo-Json -Compress
|}
|
|function Get-SILicenceRequestStatus {
|    <#
|        The licence request state for the health check and the admin: @{ Status; RequestId; RequestedUtc; NextPollUtc;
|        LastCheckUtc; ValidTo; Reason; LastError; Summary }. -Json is the stored state (SI-LicenceRequest-State).
|    #>
|    param([AllowNull()][string]$Json)
|    $s = ConvertFrom-SILicenceRequestState -Json $Json
|    $when = { param($d) if ($d) { ([datetime]$d).ToString('yyyy-MM-dd HH:mm', [Globalization.CultureInfo]::InvariantCulture) + 'Z' } else { '-' } }
|    $summary = switch ($s.status) {
|        'requested' { "licence requested on {0}, waiting for Invardia" -f (& $when $s.requestedUtc) }
|        'pending'   { "licence requested on {0}, waiting for Invardia (next check {1})" -f (& $when $s.requestedUtc), (& $when $s.nextPollUtc) }
|        'approved'  { "licence installed{0}" -f $(if ($s.validTo) { ", valid until $($s.validTo)" } else { '' }) }
|        'rejected'  { "the licence request was REJECTED on {0}{1}" -f (& $when $s.rejectedUtc), $(if ($s.reason) { ": $($s.reason)" } else { '' }) }
|        default     { if ($s.validTo) { "no request needed -- the licence is valid until $($s.validTo)" } else { 'no licence has been requested' } }
|    }
|    if ($s.lastError) { $summary += " (last problem: $($s.lastError))" }
|    [pscustomobject]@{ Status = $s.status; RequestId = $s.requestId; RequestedUtc = $s.requestedUtc; NextPollUtc = $s.nextPollUtc
|                       LastCheckUtc = $s.lastCheckUtc; ValidTo = $s.validTo; Reason = $s.reason; LastError = $s.lastError; Summary = $summary }
|}
|
|function ConvertTo-SILicenceSummaryJson {
|    <#
|        The INSTALLED licence for the Pro web app's Licence card, as compact JSON for cfg.InstallState 'Licence'
|        (NVARCHAR(400)): what Get-SILicense verified offline (signature, dates) plus whether it names this tenant. Never
|        the licence text or its signature -- the web app shows these facts and reads no secret.
|          status      Valid | Grace | Expired | NotYetValid | Invalid | Missing (the verifier's word)
|          tenantOk    true = bound to this tenant or to none; false = bound to others; null = this tenant is not proven
|          limits      only for Pro Business: the signed limits ({ "devices": 250 }); absent = Pro Enterprise
|    #>
|    param([AllowNull()]$License, [AllowNull()][string]$TenantId, [Parameter(Mandatory)][datetime]$NowUtc)
|    $day = { param($d) if ($d) { ([datetime]$d).ToString('yyyy-MM-dd', [Globalization.CultureInfo]::InvariantCulture) } else { '' } }
|    $short = { param($t, [int]$n) $t = "$t"; if ($t.Length -gt $n) { $t.Substring(0, $n - 3) + '...' } else { $t } }
|    $st = if ($License) { "$($License.Status)" } else { 'Missing' }
|    if ($st -notin @('Valid', 'Grace', 'Expired', 'NotYetValid', 'Invalid', 'Missing')) { $st = 'Invalid' }
|    $ids = @(if ($License) { @($License.TenantIds) | Where-Object { $_ } | ForEach-Object { "$_".Trim().ToLowerInvariant() } })
|    $tenantOk = $null
|    if ($ids.Count -eq 0) { $tenantOk = $true }
|    elseif ((Test-SILicenceRequestTenantProven $TenantId)) { $tenantOk = ($ids -contains "$TenantId".Trim().ToLowerInvariant()) }
|    $o = [ordered]@{
|        status      = $st
|        licenceId   = (& $short $(if ($License) { $License.LicenseId }) 40)
|        customer    = (& $short $(if ($License) { $License.Customer }) 60)
|        sku         = (& $short $(if ($License -and $st -ne 'Missing') { $License.Sku }) 20)
|        features    = (& $short $(if ($License) { (@($License.Features) | Where-Object { $_ }) -join ', ' }) 60)
|        tenantOk    = $tenantOk
|        validFrom   = (& $day $(if ($License) { $License.ValidFrom }))
|        validTo     = (& $day $(if ($License) { $License.ValidTo }))
|        graceUntil  = (& $day $(if ($License) { $License.GraceUntil }))
|        reason      = (& $short $(if ($License) { $License.Reason }) 70)
|        verifiedUtc = $NowUtc.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture)
|    }
|    # LICENCE-DIMENSION: the signed limits of a Pro Business licence (absent = Pro Enterprise), at most four, as Get-SILicense
|    # read them; the feature list gives up room so the summary still fits its 400 characters.
|    if ($License -and $License.PSObject.Properties['Limits'] -and $License.Limits -is [System.Collections.IDictionary] -and $st -ne 'Missing') {
|        $lim = [ordered]@{}
|        foreach ($k in @($License.Limits.Keys) | Select-Object -First 4) { $lim[(& $short $k 16)] = [int]$License.Limits[$k] }
|        $o['features'] = (& $short $o['features'] 30)
|        $o['limits'] = $lim
|    }
|    $o | ConvertTo-Json -Compress
|}
|
|# =====================================================================================================================
|#  HTTP (the default seam)
|# =====================================================================================================================
|function Invoke-SILicenceRequestHttp {
|    <#
|        One POST to Invardia with a JSON body. Returns @{ Status (0 = no answer); Body; RetryAfter; Error }; never throws.
|        The pull token goes in the header only, and no error text here can carry it (headers are not in exception text).
|    #>
|    param([Parameter(Mandatory)][string]$Uri, [Parameter(Mandatory)][string]$Body, [AllowNull()][string]$Token, [int]$TimeoutSec = 30,
|          # the install key proves the knock comes from this tenant's install (a header only; never in a message)
|          [AllowNull()][string]$InstallKey,
|          # Invardia S16: the install's lasting id (SI-InstallId) -> X-Invardia-Install-Id, only when it is a GUID; '' = no header
|          [AllowNull()][AllowEmptyString()][string]$InstallId = '')
|    $h = @{ Accept = 'application/json' }
|    if ($Token) { $h[$script:SILicenceRequestTokenHeader] = $Token }
|    if ($InstallKey) { $h['X-Invardia-Install-Key'] = $InstallKey }
|    $h = Add-SIInvardiaInstallIdHeader -Headers $h -InstallId $InstallId
|    try {
|        $r = Invoke-WebRequest -Method Post -Uri $Uri -Headers $h -Body $Body -ContentType 'application/json' -UseBasicParsing -TimeoutSec $TimeoutSec -ErrorAction Stop
|        $content = $r.Content; if ($content -is [byte[]]) { $content = [System.Text.Encoding]::UTF8.GetString($content) }
|        return [pscustomobject]@{ Status = [int]$r.StatusCode; Body = [string]$content; RetryAfter = 0; Error = '' }
|    } catch {
|        $resp = $null; try { $resp = $_.Exception.Response } catch { }
|        if (-not $resp) { return [pscustomobject]@{ Status = 0; Body = ''; RetryAfter = 0; Error = "$($_.Exception.Message)" } }
|        $code = 0; try { $code = [int]$resp.StatusCode } catch { }
|        $body = ''
|        if ($_.ErrorDetails -and $_.ErrorDetails.Message) { $body = [string]$_.ErrorDetails.Message }
|        elseif ($resp -is [System.Net.WebResponse]) {
|            try { $sr = New-Object System.IO.StreamReader($resp.GetResponseStream()); $body = $sr.ReadToEnd(); $sr.Close() } catch { }
|        }
|        $ra = 0
|        try {
|            if ($resp -is [System.Net.WebResponse]) { [void][int]::TryParse([string]$resp.Headers['Retry-After'], [ref]$ra) }
|            elseif ($resp.Headers.RetryAfter) { if ($resp.Headers.RetryAfter.Delta) { $ra = [int]$resp.Headers.RetryAfter.Delta.Value.TotalSeconds } }
|        } catch { }
|        return [pscustomobject]@{ Status = $code; Body = $body; RetryAfter = $ra; Error = "HTTP $code" }
|    }
|}
|
|# =====================================================================================================================
|#  The cycle
|# =====================================================================================================================
|function Invoke-SILicenceRequest {
|    <#
|        One licence request cycle: decide, knock or pull, verify, install, record. NEVER throws -- a failure is a warning
|        and a result with Action 'error' / 'network', so an update run that calls this is never failed by it.
|
|        -Seams (hashtable of scriptblocks):
|          Http          { param($Uri, $Body, $Token, $InstallKey, $InstallId) }  -> @{ Status; Body; RetryAfter; Error }   (default Invoke-SILicenceRequestHttp)
|                        (the knock passes the install key and -- Invardia S16 -- the lasting install id, '' when it is not a GUID)
|          ReadSecret    { param($Name) }  -> text or $null                                         (required)
|          WriteSecret   { param($Name, $Value) }                                                   (required)
|          TenantId      { }  -> the tenant id from the identity's TOKEN                            (required)
|          Install       { param($Text, $TenantId) } -> @{ Ok; Message }  (setup/Set-SILicense.ps1) (required)
|          CurrentLicence{ } -> the installed licence's status (default: Get-SILicense of SI-License)
|          Verify        { param($Licence, $TenantId) } -> Test-SILicenceRequestFile result         (default)
|          SaveState     { param($CompactJson) }  the Pro database mirror                          (optional)
|          Now           { } -> [datetime] UTC                                                      (default)
|          Log           { param($Level, $Text) }  Level = info | warn                              (default Write-Host / Write-Warning)
|        Returns @{ Status; Action; Message; Problems; State }.
|          Action: none | waiting | knocked | pending | installed | refused | rejected | invalid | network | error
|    #>
|    [CmdletBinding()]
|    param(
|        [Parameter(Mandatory)][System.Collections.IDictionary]$Seams,
|        [Parameter(Mandatory)][string]$Version,
|        [string]$BaseUrl,
|        [string]$Edition,
|        [string]$ContactEmail,
|        [int]$TimeoutSec = 30,
|        [AllowNull()][string[]]$TrustedCertsB64,
|        [switch]$Force
|    )
|    $log = if ($Seams['Log']) { $Seams['Log'] } else { { param($l, $t) if ($l -eq 'warn') { Write-Warning $t } else { Write-Host ("  [licence] {0}" -f $t) } } }
|    $nowF = if ($Seams['Now']) { $Seams['Now'] } else { { [datetime]::UtcNow } }
|    $problems = New-Object System.Collections.Generic.List[string]
|    $state = ConvertFrom-SILicenceRequestState -Json $null
|    $result = { param($action, $msg) [pscustomobject]@{ Status = $state.status; Action = $action; Message = $msg; Problems = $problems.ToArray(); State = (Get-SILicenceRequestStatus -Json (ConvertTo-SILicenceRequestStateJson -State $state)) } }
|    $save = {
|        try { & $Seams.WriteSecret $script:SILicenceRequestSecretState (ConvertTo-SILicenceRequestStateJson -State $state) }
|        catch { & $log 'warn' ("the licence request state could not be saved: {0}" -f $_.Exception.Message) }
|        if ($Seams['SaveState']) {
|            try { & $Seams.SaveState (ConvertTo-SILicenceRequestStateJson -State $state -Compact) }
|            catch { & $log 'warn' ("the licence request state could not be shown in the Pro database: {0}" -f $_.Exception.Message) }
|        }
|    }
|    try {
|        foreach ($req in 'ReadSecret', 'WriteSecret', 'TenantId', 'Install') { if (-not $Seams[$req]) { throw "the licence request client needs the '$req' seam" } }
|        # (no GetNewClosure anywhere a file function is called: a closure cannot see functions dot-sourced into a caller's scope)
|        $http = if ($Seams['Http']) { $Seams['Http'] } else { { param($u, $b, $t, $k, $iid) Invoke-SILicenceRequestHttp -Uri $u -Body $b -Token $t -TimeoutSec $TimeoutSec -InstallKey $k -InstallId $iid } }
|        $base = Get-SILicenceRequestBaseUrl -BaseUrl $BaseUrl
|        $now = ([datetime](& $nowF)).ToUniversalTime()
|        $state = ConvertFrom-SILicenceRequestState -Json (& $Seams.ReadSecret $script:SILicenceRequestSecretState)
|        $state.lastCheckUtc = $now
|
|        # ---- the REAL tenant, from the identity's token. Unproven = nothing is sent. ----
|        $tenant = $null
|        try { $tenant = [string](& $Seams.TenantId) } catch { $tenant = $null }
|        if (-not (Test-SILicenceRequestTenantProven $tenant)) {
|            $state.lastError = 'the tenant this install runs in could not be proven from its identity token -- nothing was sent'
|            & $log 'warn' $state.lastError
|            & $save
|            return (& $result 'refused' $state.lastError)
|        }
|        $tenant = $tenant.ToLowerInvariant()
|
|        # ---- what is installed now ----
|        $readCurrent = {
|            if ($Seams['CurrentLicence']) { return (& $Seams.CurrentLicence) }
|            $t = & $Seams.ReadSecret $script:SILicenceRequestSecretLic
|            if (-not (Get-Command -Name Get-SILicense -ErrorAction SilentlyContinue)) { return $null }
|            if ($TrustedCertsB64) { Get-SILicense -SecretText "$t" -TrustedCertsB64 $TrustedCertsB64 -Now $now } else { Get-SILicense -SecretText "$t" -Now $now }
|        }
|        $current = & $readCurrent
|        # #517: Invardia answered a status report that the installed licence was re-issued (the engine recorded the newest id;
|        # seam SupersededBy) -- ask now, once per id
|        $sup = ''
|        if ($Seams['SupersededBy']) { try { $sup = "$(& $Seams.SupersededBy)".Trim().ToLowerInvariant() } catch { $sup = '' } }
|        if ($sup -and $sup -eq "$($state.supersededHandled)".Trim().ToLowerInvariant()) { $sup = '' }
|        $need = Test-SILicenceRequestNeeded -License $current -TenantId $tenant -NowUtc $now -SupersededBy $sup
|        if ($need.ValidTo) { $state.validTo = $need.ValidTo.ToString('yyyy-MM-dd', [Globalization.CultureInfo]::InvariantCulture) } else { $state.validTo = '' }
|        $state.licenceId = "$($need.LicenceId)"
|        $poll = if ($state.pollAfterSeconds -gt 0) { [int]$state.pollAfterSeconds } else { $script:SILicenceRequestPollSeconds }
|        $open = ($state.status -in @('requested', 'pending')) -and $state.requestId
|
|        if (-not $need.Needed -and -not $open) {
|            if ($state.status -ne 'approved') { $state.status = 'none' }
|            $state.lastError = ''; $state.lastResult = $need.Reason
|            & $save
|            return (& $result 'none' ("no licence request needed: {0}" -f $need.Reason))
|        }
|        if (-not $need.Needed -and $open) {
|            # A valid licence arrived another way (installed by hand): the open request is no longer this install's business.
|            $state.status = 'none'; $state.requestId = ''; $state.nextPollUtc = $null; $state.lastError = ''; $state.lastResult = $need.Reason
|            & $save
|            return (& $result 'none' ("no licence request needed: {0}" -f $need.Reason))
|        }
|
|        # ---- KNOCK (a local block, so a 401 on pull can knock in the same run) ----
|        $knock = {
|            param([string]$Why)
|            # Invardia S16: with the vault's versions (ReadVersions) the id is the FIRST one written, whichever side wrote it
|            $iid = if ($Seams['ReadVersions']) { Resolve-SIInvardiaInstallId -ReadSecret $Seams.ReadSecret -WriteSecret $Seams.WriteSecret -ReadVersions $Seams['ReadVersions'] -ReplaceNotGuid }
|                   else { "$(& $Seams.ReadSecret $script:SILicenceRequestSecretId)".Trim() }
|            if ($iid -notmatch '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$') {
|                # kept for good: every later knock reuses it. Made by the SAME code as the uplink job's (Invardia S16): a GUID,
|                # written, read back -- when both make it at once, the one the vault kept is sent by both
|                $iid = Resolve-SIInvardiaInstallId -ReadSecret $Seams.ReadSecret -WriteSecret $Seams.WriteSecret -ReadVersions $Seams['ReadVersions'] -ReplaceNotGuid
|                if (-not $iid) { throw 'the install id (SI-InstallId) could not be kept in the Key Vault' }
|            }
|            $cv = $null; $cid = ''
|            if ($current -and "$($current.Status)" -notin @('Missing', 'Invalid')) { $cid = "$($current.LicenseId)"; $cv = $need.ValidTo }
|            # the proof that this install holds the tenant's licence: the SHA-256 of the licence file as it is kept here
|            # (UTF-8, no byte order mark, trimmed -- how Test-SILicenceRequestFile stores it), and the install key in the header
|            $csha = ''
|            try { $lt = "$(& $Seams.ReadSecret $script:SILicenceRequestSecretLic)".TrimStart([char]0xFEFF).Trim(); if ($lt -and $lt -ne '-') { $csha = Get-SILicenceRequestSha256 -Bytes ([System.Text.Encoding]::UTF8.GetBytes($lt)) } } catch { $csha = '' }
|            $ikey = ''
|            try { $ikey = "$(& $Seams.ReadSecret 'SI-Invardia-InstallKey')".Trim(); if ($ikey -notmatch '^inv-[^\s]{8,}$') { $ikey = '' } } catch { $ikey = '' }
|            $body = New-SILicenceRequestBody -Version $Version -TenantId $tenant -InstallId $iid -Edition $Edition -ContactEmail $ContactEmail -CurrentLicenceId $cid -CurrentValidTo $cv -CurrentLicenceSha256 $csha
|            & $log 'info' ("asking Invardia for a licence ({0}) for tenant {1}" -f $Why, $tenant)
|            # Invardia S16: the same lasting id as X-Invardia-Install-Id (the knock only -- the pull carries its token, no id)
|            $r = & $http ($base + '/api/licence-requests') $body $null $ikey (ConvertTo-SIInvardiaInstallId $iid)
|            $code = [int]$r.Status
|            if ($code -in @(200, 201, 202)) {
|                $j = $null; try { $j = "$($r.Body)" | ConvertFrom-Json -ErrorAction Stop } catch { }
|                if (-not $j -or -not "$($j.pullToken)".Trim() -or -not "$($j.requestId)".Trim()) {
|                    $state.lastError = 'Invardia accepted the request but sent no request id or pull token'
|                    $state.nextKnockUtc = $now.AddSeconds($script:SILicenceRequestPollSeconds)
|                    & $log 'warn' $state.lastError
|                    return 'error'
|                }
|                & $Seams.WriteSecret $script:SILicenceRequestSecretToken ([string]$j.pullToken)   # a repeat knock's NEW token replaces the old
|                $pa = 0; [void][int]::TryParse("$($j.pollAfterSeconds)", [ref]$pa)
|                $state.pollAfterSeconds = $(if ($pa -gt 0) { $pa } else { $script:SILicenceRequestPollSeconds })
|                $state.requestId = [string]$j.requestId
|                $state.requestedUtc = $now
|                $state.status = 'requested'
|                $state.reason = ''; $state.rejectedUtc = $null; $state.lastError = ''; $state.nextKnockUtc = $null
|                $state.nextPollUtc = $(if ("$($j.status)" -eq 'Approved') { $now } else { $now.AddSeconds($state.pollAfterSeconds) })
|                $state.lastResult = "requested ($($j.status))"
|                & $log 'info' ("licence requested (request {0}, {1}); next check after {2:yyyy-MM-dd HH:mm}Z" -f $state.requestId, $j.status, $state.nextPollUtc)
|                return $(if ("$($j.status)" -eq 'Approved') { 'approved-now' } else { 'knocked' })
|            }
|            return (& $failed $r 'knock')
|        }
|        # ---- an answer that is not success (knock or pull): record it, decide when to try again ----
|        $failed = {
|            param($r, [string]$What)
|            $code = [int]$r.Status
|            $next = $now.AddSeconds($poll)
|            $kind = 'network'
|            if ($code -eq 0) {
|                $state.lastError = ("Invardia could not be reached ({0}): {1}" -f $What, $r.Error)
|            } elseif ($code -eq 429) {
|                $ra = [int]$r.RetryAfter; if ($ra -le 0) { $ra = 60 }
|                $next = $now.AddSeconds([Math]::Max($ra, $(if ($What -eq 'pull') { $poll } else { 0 })))
|                $state.lastError = ("Invardia asked to slow down ({0}); next try after {1} s" -f $What, [int]($next - $now).TotalSeconds)
|                $kind = 'waiting'
|            } elseif ($code -eq 422) {
|                $fields = @(); try { $fields = @(("$($r.Body)" | ConvertFrom-Json -ErrorAction Stop).fields | ForEach-Object { if ($_ -is [string]) { $_ } elseif ($_.PSObject.Properties['field']) { "$($_.field)" } elseif ($_.PSObject.Properties['name']) { "$($_.name)" } else { ($_ | ConvertTo-Json -Compress) } }) } catch { }
|                $next = $now.AddHours($script:SILicenceRequestInvalidHours)
|                $state.lastError = ("Invardia refused the {0} as invalid; fields: {1}. It is not repeated before {2:yyyy-MM-dd HH:mm}Z" -f $What, $(if ($fields.Count) { $fields -join ', ' } else { 'none named' }), $next)
|                foreach ($f in $fields) { $problems.Add("invalid field: $f") }
|                $kind = 'invalid'
|            } elseif ($code -ge 400 -and $code -lt 500) {
|                $state.lastError = ("Invardia answered {0} to the {1}" -f $code, $What)
|                $kind = 'error'
|            } else {
|                $state.lastError = ("Invardia answered {0} to the {1} -- tried again on a later run" -f $code, $What)
|            }
|            if ($What -eq 'knock') { $state.nextKnockUtc = $next } else { $state.nextPollUtc = $next }
|            & $log 'warn' $state.lastError
|            return $kind
|        }
|
|        # ---- PULL ----
|        $pull = {
|            $tok = "$(& $Seams.ReadSecret $script:SILicenceRequestSecretToken)".Trim()
|            if (-not $tok -or $tok -eq '-') { return 'reknock' }
|            $r = & $http ($base + '/api/licence-requests/pull') '{}' $tok
|            $tok = $null
|            $code = [int]$r.Status
|            if ($code -eq 401) { & $log 'info' 'the pull token is no longer accepted -- asking again'; return 'reknock' }
|            if ($code -ne 200) { return (& $failed $r 'pull') }
|            $j = $null; try { $j = "$($r.Body)" | ConvertFrom-Json -ErrorAction Stop } catch { }
|            $st = if ($j) { "$($j.status)" } else { '' }
|            switch ($st) {
|                'Rejected' {
|                    $state.status = 'rejected'; $state.reason = $(if ($j.PSObject.Properties['reason']) { "$($j.reason)" } else { '' })
|                    $state.rejectedUtc = $now; $state.nextPollUtc = $null; $state.lastError = ''
|                    $state.lastResult = 'rejected'
|                    & $Seams.WriteSecret $script:SILicenceRequestSecretToken '-'
|                    & $log 'warn' ("the licence request was REJECTED by Invardia{0}. It is not asked again automatically before {1:yyyy-MM-dd}; run setup/Request-SILicense.ps1 -Force to ask now." -f $(if ($state.reason) { ": $($state.reason)" } else { '' }), $now.AddDays($script:SILicenceRequestRejectDays))
|                    return 'rejected'
|                }
|                'Approved' {
|                    if (-not $j.PSObject.Properties['licence'] -or $null -eq $j.licence) { break }
|                    $verify = if ($Seams['Verify']) { $Seams['Verify'] } else { { param($l, $t) Test-SILicenceRequestFile -Licence $l -TenantId $t -TrustedCertsB64 $TrustedCertsB64 -Now $now } }
|                    $v = & $verify $j.licence $tenant
|                    if (-not $v.Ok) {
|                        foreach ($p in @($v.Problems)) { $problems.Add($p) }
|                        $state.status = 'pending'; $state.nextPollUtc = $now.AddSeconds($poll)
|                        $state.lastError = ("the licence Invardia sent was NOT installed: {0}" -f (@($v.Problems) -join '; '))
|                        & $log 'warn' $state.lastError
|                        return 'refused'
|                    }
|                    $ins = $null
|                    try { $ins = & $Seams.Install $v.Text $tenant } catch { $ins = [pscustomobject]@{ Ok = $false; Message = $_.Exception.Message } }
|                    if (-not $ins -or -not $ins.Ok) {
|                        $state.status = 'pending'; $state.nextPollUtc = $now.AddSeconds($poll)
|                        $state.lastError = ("the licence verified but could not be installed: {0}" -f $(if ($ins) { $ins.Message } else { 'no result' }))
|                        & $log 'warn' $state.lastError
|                        return 'error'
|                    }
|                    # Read it back: what the engines will read must be the licence just verified.
|                    $back = & $readCurrent
|                    if (-not $back -or "$($back.Status)" -ne 'Valid' -or "$($back.LicenseId)" -ne "$($v.License.LicenseId)") {
|                        $state.status = 'pending'; $state.nextPollUtc = $now.AddSeconds($poll)
|                        $state.lastError = 'the licence was written but did not read back as the one verified'
|                        & $log 'warn' $state.lastError
|                        return 'error'
|                    }
|                    $state.status = 'approved'; $state.requestId = ''; $state.nextPollUtc = $null; $state.lastError = ''; $state.reason = ''
|                    $state.validTo = ([datetime]$v.License.ValidTo).ToString('yyyy-MM-dd', [Globalization.CultureInfo]::InvariantCulture)
|                    $state.licenceId = "$($v.License.LicenseId)"
|                    $state.lastResult = 'installed'
|                    & $Seams.WriteSecret $script:SILicenceRequestSecretToken '-'
|                    & $log 'info' ("licence installed and read back: valid until {0}" -f $state.validTo)
|                    return 'installed'
|                }
|            }
|            # Pending, or Approved but not signed yet
|            $state.status = 'pending'; $state.nextPollUtc = $now.AddSeconds($poll); $state.lastError = ''; $state.lastResult = 'pending'
|            & $log 'info' ("waiting for Invardia (request {0}); next check after {1:yyyy-MM-dd HH:mm}Z" -f $state.requestId, $state.nextPollUtc)
|            return 'pending'
|        }
|
|        $action = $null
|        if ($open) {
|            $tokenAge = if ($state.requestedUtc) { ($now - [datetime]$state.requestedUtc).TotalDays } else { 999 }
|            if ($tokenAge -ge $script:SILicenceRequestTokenDays) {
|                $action = 'reknock'
|            } elseif (-not $Force -and $state.nextPollUtc -and $now -lt [datetime]$state.nextPollUtc) {
|                $state.lastResult = 'waiting'
|                & $save
|                return (& $result 'waiting' ("waiting for Invardia (request {0}); next check after {1:yyyy-MM-dd HH:mm}Z" -f $state.requestId, $state.nextPollUtc))
|            } else {
|                $action = & $pull
|            }
|            if ($action -ne 'reknock') { & $save; return (& $result $action $(if ($state.lastError) { $state.lastError } else { Get-SILicenceRequestStatus -Json (ConvertTo-SILicenceRequestStateJson -State $state) | ForEach-Object { $_.Summary } })) }
|        }
|
|        # ---- no open request (or its token is gone): knock, unless a rejection or a refusal says wait ----
|        if (-not $Force -and $state.status -eq 'rejected' -and $state.rejectedUtc -and $now -lt ([datetime]$state.rejectedUtc).AddDays($script:SILicenceRequestRejectDays)) {
|            & $save
|            return (& $result 'rejected' ("the licence request was rejected{0}; not asked again before {1:yyyy-MM-dd} (setup/Request-SILicense.ps1 -Force asks now)" -f $(if ($state.reason) { ": $($state.reason)" } else { '' }), ([datetime]$state.rejectedUtc).AddDays($script:SILicenceRequestRejectDays)))
|        }
|        if (-not $Force -and $action -ne 'reknock' -and $state.nextKnockUtc -and $now -lt [datetime]$state.nextKnockUtc) {
|            & $save
|            return (& $result 'waiting' ("not asking again before {0:yyyy-MM-dd HH:mm}Z{1}" -f $state.nextKnockUtc, $(if ($state.lastError) { " ($($state.lastError))" } else { '' })))
|        }
|        $why = if ($action -eq 'reknock') { 'the pull token expired or was not accepted' } else { $need.Reason }
|        $k = & $knock $why
|        if ($need.Superseded -and $k -in @('knocked', 'approved-now')) { $state.supersededHandled = $sup }
|        if ($k -eq 'approved-now') { $k = & $pull; if ($k -eq 'reknock') { $k = 'error'; $state.lastError = 'the new pull token was not accepted' } }
|        & $save
|        return (& $result $k $(if ($state.lastError) { $state.lastError } else { (Get-SILicenceRequestStatus -Json (ConvertTo-SILicenceRequestStateJson -State $state)).Summary }))
|    } catch {
|        $msg = "the licence request did not complete: $($_.Exception.Message)"
|        try { $state.lastError = $msg; & $save } catch { }
|        & $log 'warn' $msg
|        return (& $result 'error' $msg)
|    }
|}
|
|# =====================================================================================================================
|#  The real seams
|# =====================================================================================================================
|function New-SILicenceRequestSeams {
|    <#
|        The seams for a real run, against the install's Key Vault -- over REST through SecurityInsight's own sign-in
|        (engine/_shared/SI-AzRest.ps1: Get-SIAzKeyVaultSecret / Set-SIAzKeyVaultSecret; #521, no az CLI):
|          -Mode Rest   the updater job (signed in once by Connect-SIUpdateRest: its managed identity or certificate).
|          -Mode Az     the same REST client, as setup/Request-SILicense.ps1 names it on an admin machine or VM.
|        The tenant is the tid of the managed identity's token when the install signs in as one, else of the run's own token.
|        Install = setup/Set-SILicense.ps1 of -SIRoot (it verifies again and reads the secret back).
|    #>
|    param([Parameter(Mandatory)][string]$VaultName, [ValidateSet('Az', 'Rest')][string]$Mode = 'Az', [string]$SubscriptionId, [string]$SIRoot)
|    if (-not $SIRoot) { $SIRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot) }
|    $setter = [IO.Path]::Combine($SIRoot, 'setup', 'Set-SILicense.ps1')
|    $vault = $VaultName
|    $s = @{}
|    # The closures need $vault, but a closure cannot see functions dot-sourced into a caller's SCRIPT scope: run as
|    # `.\Request-SILicense.ps1` from a prompt (or from another script) it failed with "Get-SIAzKeyVaultSecret is not
|    # recognized" (found live on ring 1, 2026-10-05). So the functions are captured here and called by reference.
|    $kvGet = ${function:Get-SIAzKeyVaultSecret}; $kvSet = ${function:Set-SIAzKeyVaultSecret}
|    $atGet = ${function:Get-SIAzAccessToken}; $tidOf = ${function:Get-SILicenceRequestTenantFromToken}
|    $miTok = ${function:Get-SIManagedIdentityToken}
|    $kvVers = ${function:Get-SIInvardiaKvInstallIdVersions}
|    # A function the closures need and this job did not load is named in a plain error at the call -- never an opaque
|    # "& $null" and never a different sign-in path taken silently.
|    $need = { param([string]$Fn, $Value) if (-not $Value) { throw ("the licence request cannot run: {0} is not loaded in this job (engine\_shared\SI-AzRest.ps1)" -f $Fn) } }
|    $s.ReadSecret = {
|        param([string]$Name)
|        & $need 'Get-SIAzKeyVaultSecret' $kvGet
|        $sec = & $kvGet -VaultName $vault -Name $Name -ErrorAction Stop
|        if (-not $sec) { return $null }
|        [System.Net.NetworkCredential]::new('', $sec.SecretValue).Password
|    }.GetNewClosure()
|    $s.WriteSecret = {
|        param([string]$Name, [string]$Value)
|        & $need 'Set-SIAzKeyVaultSecret' $kvSet
|        $null = & $kvSet -VaultName $vault -Name $Name -SecretValue (ConvertTo-SecureString -String $Value -AsPlainText -Force) -ErrorAction Stop
|    }.GetNewClosure()
|    # Invardia S16: the versions of SI-InstallId (first write wins) -- the same vault, over the same REST sign-in
|    if ($kvVers) {
|        $s.ReadVersions = {
|            param([string]$Name)
|            & $kvVers -VaultName $vault -Name $Name
|        }.GetNewClosure()
|    }
|    $s.TenantId = {
|        if ([bool]$global:SI_UseManagedIdentity) {
|            # the install signs in as its managed identity: the tenant is that token's (auth\SI-ManagedIdentity.ps1)
|            # (a guided install sets its token hook as the global function after the seams may have been made -- it is taken
|            # then; every copy of the function asks $global:SI_InstallTokenProvider first, so the captured one is right too)
|            $mi = $miTok; if (-not $mi) { $c = Get-Command -Name Get-SIManagedIdentityToken -CommandType Function -ErrorAction SilentlyContinue; if ($c) { $mi = $c.ScriptBlock } }
|            if (-not $mi) { throw 'the licence request cannot read the tenant: the install signs in as its managed identity and Get-SIManagedIdentityToken is not loaded in this job (auth\SI-ManagedIdentity.ps1)' }
|            $null = & $mi -Resource 'https://management.azure.com/'
|            return [string]$global:SI_IdentityTokenTenantId
|        }
|        & $need 'Get-SIAzAccessToken' $atGet; & $need 'Get-SILicenceRequestTenantFromToken' $tidOf
|        $t = & $atGet -ResourceUrl 'https://management.azure.com/' -ErrorAction Stop
|        $tok = if ($t.Token -is [System.Security.SecureString]) { [System.Net.NetworkCredential]::new('', $t.Token).Password } else { [string]$t.Token }
|        & $tidOf -AccessToken $tok
|    }.GetNewClosure()
|    $s.Install = {
|        param([string]$Text, [string]$TenantId)
|        if (-not (Test-Path -LiteralPath $setter)) { return [pscustomobject]@{ Ok = $false; Message = "setup/Set-SILicense.ps1 is not in this copy ($setter)" } }
|        $f = [IO.Path]::Combine([IO.Path]::GetTempPath(), 'si-lr-' + [guid]::NewGuid().ToString('N') + '.silicense')
|        [IO.File]::WriteAllText($f, $Text, (New-Object System.Text.UTF8Encoding($false)))
|        try {
|            $a = @{ Path = $f; VaultName = $vault; TenantId = $TenantId; Confirm = $false }
|            $null = & $setter @a 6>$null
|            [pscustomobject]@{ Ok = $true; Message = 'installed' }
|        } catch { [pscustomobject]@{ Ok = $false; Message = $_.Exception.Message } }
|        finally { Remove-Item -LiteralPath $f -Force -ErrorAction SilentlyContinue }
|    }.GetNewClosure()
|    $s
|}
'@ }
$__siSupportFiles['engine/_shared/SI-LicenceSuperseded.ps1'] = @{ Sha256 = '5da16885e4d22cddd570e1036645e9781a59c301218738c9f61aa6991ccb2ac9'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- A RE-ISSUED LICENCE REACHES THE INSTALL BY ITSELF (#517; framework DOCS/REQUIREMENTS.md §12.6b,
|    Invardia live 1.0.230).
|
|    HOW: every IDENTIFIED status report carries the installed licence's id (LicenceId, a lower-case GUID -- left out when
|    the licence has no GUID-shaped id, else Invardia refuses the whole report). When Invardia has re-issued that licence it
|    answers 202 {"supersededBy": "<newest id>"}. The engine run that hears it records the id here, in the Pro database
|    (cfg.InstallState 'LicenceSupersededBy', on the connection the run already has); the updater's licence step reads it on
|    its next run and knocks at once with currentLicenceId -- Invardia then approves the successor by itself and the normal
|    pull installs it (verified offline as every licence is). The same id is knocked for only once.
|
|    The marker only says "ask now"; nothing is trusted from it -- the licence itself is verified as always. PS 5.1 + 7.
|#>
|
|function Get-SILicenceSupersededNameState {
|    <# The value of $script:SILicenceSupersededName, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SILicenceSupersededName) { $script:SILicenceSupersededName = 'LicenceSupersededBy' }
|    , $script:SILicenceSupersededName
|}
|$script:SILicenceSupersededName = $null; $null = Get-SILicenceSupersededNameState
|function Get-SILicenceSupersededGuidState {
|    <# The value of $script:SILicenceSupersededGuid, made on first use in the scope that reads it: a function loaded by an outer script and called from an engine's script finds it set (the lists never depend on the caller's scope). #>
|    if ($null -eq $script:SILicenceSupersededGuid) { $script:SILicenceSupersededGuid = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' }
|    , $script:SILicenceSupersededGuid
|}
|$script:SILicenceSupersededGuid = $null; $null = Get-SILicenceSupersededGuidState
|
|function ConvertTo-SILicenceIdOrEmpty {
|    <# PURE. A licence id as the lower-case GUID Invardia takes, or '' when it is not GUID-shaped. #>
|    param([AllowNull()][AllowEmptyString()][string]$LicenceId)
|    $v = "$LicenceId".Trim()
|    if ($v -match (Get-SILicenceSupersededGuidState)) { return $v.ToLowerInvariant() }
|    ''
|}
|
|function Get-SILicenceSupersededFromAnswer {
|    <# PURE. The supersededBy id of an uplink answer (a parsed body, or its text), '' when none / not a GUID. #>
|    param([AllowNull()]$Answer)
|    if ($null -eq $Answer) { return '' }
|    $o = $Answer
|    if ($Answer -is [string]) { if (-not $Answer.Trim()) { return '' }; try { $o = $Answer | ConvertFrom-Json -ErrorAction Stop } catch { return '' } }
|    $v = ''
|    if ($o -is [System.Collections.IDictionary]) { if ($o.Contains('supersededBy')) { $v = [string]$o['supersededBy'] } }
|    elseif ($o.PSObject.Properties['supersededBy']) { $v = [string]$o.supersededBy }
|    ConvertTo-SILicenceIdOrEmpty $v
|}
|
|function Save-SILicenceSupersededMark {
|    <# Records the newest licence id Invardia named (cfg.InstallState 'LicenceSupersededBy') on -Store. Throws on failure. #>
|    param([Parameter(Mandatory)]$Store, [Parameter(Mandatory)][string]$LicenceId, $NowUtc)
|    $id = ConvertTo-SILicenceIdOrEmpty $LicenceId
|    if (-not $id) { throw "not a licence id: '$LicenceId'" }
|    $at = if ($NowUtc) { ([datetime]$NowUtc).ToUniversalTime() } else { [datetime]::UtcNow }
|    $v = ([ordered]@{ licenceId = $id; seenUtc = $at.ToString('yyyy-MM-ddTHH:mm:ssZ', [Globalization.CultureInfo]::InvariantCulture) } | ConvertTo-Json -Compress)
|    $sql = @'
|IF OBJECT_ID('cfg.InstallState') IS NOT NULL
|BEGIN
|    SET XACT_ABORT ON;
|    BEGIN TRAN;
|    IF EXISTS (SELECT 1 FROM cfg.InstallState WITH (UPDLOCK, HOLDLOCK) WHERE Name = @Name)
|        UPDATE cfg.InstallState SET Value = @Value, UpdatedAt = SYSUTCDATETIME(), UpdatedBy = @By WHERE Name = @Name;
|    ELSE
|        INSERT cfg.InstallState (Name, Value, [Version], UpdatedBy) VALUES (@Name, @Value, NULL, @By);
|    COMMIT;
|END
|'@
|    $null = & $Store.Invoke $sql ([ordered]@{ Name = (Get-SILicenceSupersededNameState); Value = $v; By = 'si-engine (Invardia uplink)' }) 'nonquery'
|}
|
|function Read-SILicenceSupersededMark {
|    <# The licence id the last report heard (cfg.InstallState 'LicenceSupersededBy') on -Store, '' when none. NEVER throws. #>
|    param([Parameter(Mandatory)]$Store)
|    try {
|        $rows = @(& $Store.Invoke "IF OBJECT_ID('cfg.InstallState') IS NOT NULL SELECT Value FROM cfg.InstallState WHERE Name = N'LicenceSupersededBy'" @{} 'reader' | ForEach-Object { $_ })
|        foreach ($row in $rows) {
|            if (-not $row) { continue }
|            $v = if ($row -is [System.Collections.IDictionary]) { $row['Value'] } else { $row.Value }
|            if ($null -eq $v -or $v -is [System.DBNull]) { continue }
|            return (Get-SILicenceSupersededFromAnswer ([string]$v -replace '"licenceId"', '"supersededBy"'))
|        }
|    } catch { }
|    ''
|}
'@ }
$__siSupportFiles['engine/_shared/SI-InvardiaInstallId.ps1'] = @{ Sha256 = '9817b4a05b6021c91c6cd3bb75e61d25587364f0889a86801136e6f4270fe917'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- THE INSTALL'S LASTING ID ON ITS CALLS TO INVARDIA (Invardia S16, agreed 2026-11-01; the same contract
|    PIM 3.0.14 runs).
|
|    THE ID. One per install: the Key Vault secret SI-InstallId -- the GUID the licence request (SI-LicenceRequest.ps1)
|    created ONCE, at the install's first knock, kept next to the licence and sent as the knock body's installId on every knock
|    since. It is what Invardia already knows the install by. An update, a restart or a new container never replaces it (it
|    lives in the install's Key Vault, not in the image or on a disk; a reinstall that keeps the vault keeps the id). It is
|    CREATED ONCE when missing -- by the licence knock and (Invardia 2026-11-01) by the uplink heartbeat job -- with the same
|    code (Resolve-SIInvardiaInstallId: a GUID, written, read back), and never rewritten. Every other caller only READS it.
|    No id stored / not readable / not a GUID = NO header and NO field -- never an empty, a placeholder or a made-up value
|    (a wrong id would lock the install key at Invardia).
|
|    NOT the anonymous telemetry id (Get-SITelemetryInstallId: <state>\install-id, or derived from the storage account in a
|    container). That one identifies nothing but "the same Community install as last time"; the two are never joined.
|
|    WHERE IT GOES:
|      header X-Invardia-Install-Id (lower-case GUID) on the manifest pull (SI-InvardiaUpdate.ps1 Request-SIInvardiaManifest)
|                                     and the licence knock (SI-LicenceRequest.ps1, POST /api/licence-requests);
|      field  InstallId on every IDENTIFIED uplink record -- heartbeat, run, guard (SI-TelemetrySend.ps1,
|                                     SI-Guard.ps1, SI-GuardHeal.ps1; the health record's own installId, SI-DataHealth.ps1);
|      never on the setup report (Kind setup), an anonymous record, the key claim, the licence pull, the install-run tracking
|      or the update-now signal.
|
|    PURE helpers, no network. PS 5.1 and 7.
|#>
|
|# The names are LITERALS inside each function (no $script: state): these functions are loaded by one script and called from
|# another's scope (an engine's own script, the updater), where a file-level variable would be empty.
|
|function ConvertTo-SIInvardiaInstallId {
|    <# PURE. A GUID (any case, trimmed) -> its lower-case 8-4-4-4-12 text; anything else ($null, '', '-', not a GUID) -> ''. #>
|    param([AllowNull()][object]$Value)
|    if ($null -eq $Value) { return '' }
|    $t = "$Value".Trim().ToLowerInvariant()
|    if ($t -match '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$') { return $t }
|    return ''
|}
|
|function Select-SIInvardiaFirstInstallId {
|    <#
|        PURE. FIRST WRITE WINS (Invardia 2026-11-01): from the versions of SI-InstallId (-Versions: objects with Value, Enabled,
|        Created, Version), the OLDEST ENABLED version that holds a GUID is the install's id -- whichever side wrote it. Order:
|        Created ascending, then the version id (ordinal) so two versions made in the same second are ordered the same way by
|        every reader. Returns @{ First (the id, lower-cased, '' = none); Newest (the newest enabled version's value as stored);
|        Count (enabled versions) }.
|    #>
|    param([AllowNull()][object[]]$Versions)
|    # a seam that hands back its list as ONE object (a List, an array in an array) is read as its items
|    $flat = foreach ($x in @($Versions)) { if ($x -is [System.Collections.IEnumerable] -and $x -isnot [string] -and $x -isnot [System.Collections.IDictionary]) { foreach ($y in $x) { $y } } else { $x } }
|    $en = @(@($flat) | Where-Object { $null -ne $_ -and -not ($_.PSObject.Properties['Enabled'] -and $_.Enabled -eq $false) })
|    $key = { param($x) $c = $x.Created; if ($c -is [datetime]) { $c.ToUniversalTime().Ticks } elseif ($null -ne $c -and "$c" -match '^\d+$') { [datetime]::new(1970, 1, 1, 0, 0, 0, [DateTimeKind]::Utc).AddSeconds([double]"$c").Ticks } else { [long]::MaxValue } }
|    $sorted = @($en | Sort-Object -Property @{ Expression = { & $key $_ } }, @{ Expression = { [string]$_.Version } })
|    $first = ''
|    foreach ($x in $sorted) { $g = ConvertTo-SIInvardiaInstallId $x.Value; if ($g) { $first = $g; break } }
|    [pscustomobject]@{ First = $first; Newest = $(if ($sorted.Count) { [string]$sorted[-1].Value } else { $null }); Count = $sorted.Count }
|}
|
|function Get-SIInvardiaKvInstallIdVersions {
|    <#
|        The versions of a Key Vault secret over REST (engine\_shared\SI-AzRest.ps1, the run's own sign-in): GET
|        /secrets/<name>/versions (every page), then each enabled version's value (at most 50, oldest first, plus the newest).
|        Returns @(@{ Value; Enabled; Created; Version }); none (404) = @(). THROWS when the vault cannot be read -- a caller
|        never takes an unreadable vault for an empty one.
|    #>
|    param([Parameter(Mandatory)][string]$VaultName, [string]$Name = 'SI-InstallId')
|    $uri = 'https://{0}.vault.azure.net/secrets/{1}/versions?api-version=7.4&maxresults=25' -f $VaultName, [uri]::EscapeDataString($Name)
|    $items = New-Object System.Collections.Generic.List[object]
|    $pages = 0
|    while ($uri -and $pages -lt 20) {
|        $pages++
|        $r = Invoke-SIAzRestRequest -Method GET -Uri $uri -Audience KeyVault -AllowNotFound -What ("the versions of Key Vault secret '{0}' in '{1}'" -f $Name, $VaultName)
|        if (-not $r) { break }
|        $j = $r.Content | ConvertFrom-Json
|        foreach ($v in @($j.value)) { if ($v) { $items.Add($v) } }
|        $uri = if ($j.PSObject.Properties['nextLink'] -and "$($j.nextLink)" -match '^https://') { [string]$j.nextLink } else { $null }
|    }
|    $rows = @($items | ForEach-Object {
|        $ver = ([string]$_.id).TrimEnd('/').Split('/')[-1]
|        [pscustomobject]@{ Value = $null; Enabled = -not ($_.attributes -and $_.attributes.enabled -eq $false); Created = $(if ($_.attributes) { $_.attributes.created } else { $null }); Version = $ver }
|    } | Where-Object { $_.Enabled })
|    $order = @($rows | Sort-Object -Property @{ Expression = { if ("$($_.Created)" -match '^\d+$') { [double]"$($_.Created)" } else { [double]::MaxValue } } }, @{ Expression = { [string]$_.Version } })
|    $want = @($order | Select-Object -First 50) + @($order | Select-Object -Last 1)
|    $seen = @{}
|    foreach ($x in $want) {
|        if ($seen.ContainsKey([string]$x.Version)) { continue }; $seen[[string]$x.Version] = $true
|        # only the versions that can decide: the 50 oldest (the first GUID is among them) and the newest (the converge check)
|        $raw = Get-SIKeyVaultSecretRaw -VaultName $VaultName -Name $Name -Version $x.Version
|        if ($raw) { $x.Value = [string]$raw.value }
|    }
|    # one object per version (an empty vault returns nothing): callers wrap the call in @()
|    return $order
|}
|
|function Get-SIInvardiaInstallId {
|    <#
|        This install's lasting id, READ ONLY. With -ReadVersions { param($Name) } (the versions of SI-InstallId): the OLDEST
|        enabled version holding a GUID (first write wins); when the versions cannot be read, the current value through
|        -ReadSecret { param($Name) }. A GUID comes back lower-cased; none / not a GUID / the read failed -> ''. Never creates
|        it, never throws.
|    #>
|    param([scriptblock]$ReadSecret, [scriptblock]$ReadVersions)
|    if ($ReadVersions) {
|        try { $p = Select-SIInvardiaFirstInstallId -Versions @(& $ReadVersions 'SI-InstallId'); if ($p.First -or $p.Count) { return $p.First } } catch { }
|    }
|    if (-not $ReadSecret) { return '' }
|    $v = $null
|    try { $v = & $ReadSecret 'SI-InstallId' } catch { return '' }
|    return (ConvertTo-SIInvardiaInstallId $v)
|}
|
|function Resolve-SIInvardiaInstallId {
|    <#
|        Invardia 2026-11-01 (S16, answer 2): the lasting id, CREATED ONCE when it is missing -- by the licence knock and by the
|        uplink (heartbeat) job, with the same code and format: [guid]::NewGuid().ToString(), written to SI-InstallId.
|          * FIRST WRITE WINS (-ReadVersions): the id is the OLDEST enabled version of SI-InstallId that holds a GUID
|            (Select-SIInvardiaFirstInstallId), whichever side wrote it. A side that just wrote reads back the same way, so
|            when the knock and the uplink create at once both send the first value. When a later version holds ANOTHER GUID
|            (the losing write of such a race), the first value is written once more as the current version, so a plain read
|            (the engines' status reports) gives the same id -- the id itself never changes. One version (every install
|            before a race) behaves exactly as a plain read.
|          * without -ReadVersions, or when the versions cannot be read: the current value (-ReadSecret), as before;
|          * a stored GUID is KEPT (returned lower-cased) -- never replaced by another id;
|          * a stored value that is not a GUID is left as it is and '' comes back, unless -ReplaceNotGuid (the knock's rule
|            since #239: its body needs a GUID);
|          * the vault cannot be read or written -> '' (no id this time), never a throw.
|        -ReadSecret { param($Name) } / -WriteSecret { param($Name, $Value) } / -ReadVersions { param($Name) } -> @(@{ Value;
|        Enabled; Created; Version }).
|    #>
|    param([scriptblock]$ReadSecret, [scriptblock]$WriteSecret, [scriptblock]$ReadVersions, [switch]$ReplaceNotGuid)
|    if ($ReadVersions) {
|        $pick = { Select-SIInvardiaFirstInstallId -Versions @(& $ReadVersions 'SI-InstallId') }
|        $p = $null
|        try { $p = & $pick } catch { $p = $null }
|        if ($null -ne $p) {
|            $converge = {
|                param($sel)
|                $nw = ConvertTo-SIInvardiaInstallId $sel.Newest
|                if ($WriteSecret -and $sel.First -and $nw -and $nw -ne $sel.First) { try { $null = & $WriteSecret 'SI-InstallId' $sel.First } catch { } }
|            }
|            if ($p.First) { & $converge $p; return $p.First }
|            if ($null -ne $p.Newest -and "$($p.Newest)".Trim() -and -not $ReplaceNotGuid) { return '' }
|            if (-not $WriteSecret) { return '' }
|            $new = [guid]::NewGuid().ToString()
|            try { $null = & $WriteSecret 'SI-InstallId' $new } catch { return '' }
|            try { $p = & $pick } catch { return '' }
|            if ($p.First) { & $converge $p }
|            return [string]$p.First
|        }
|        # the versions could not be read: the plain read below (as before)
|    }
|    if (-not $ReadSecret) { return '' }
|    $v = $null
|    try { $v = & $ReadSecret 'SI-InstallId' } catch { return '' }
|    $have = ConvertTo-SIInvardiaInstallId $v
|    if ($have) { return $have }
|    if ($null -ne $v -and "$v".Trim() -and -not $ReplaceNotGuid) { return '' }
|    if (-not $WriteSecret) { return '' }
|    $new = [guid]::NewGuid().ToString()
|    try { $null = & $WriteSecret 'SI-InstallId' $new } catch { return '' }
|    $back = $null
|    try { $back = & $ReadSecret 'SI-InstallId' } catch { return '' }
|    return (ConvertTo-SIInvardiaInstallId $back)
|}
|function Add-SIInvardiaInstallIdHeader {
|    <# PURE. -Headers with X-Invardia-Install-Id = -InstallId added when it is a GUID (lower-case); unchanged otherwise. #>
|    param([AllowNull()][System.Collections.IDictionary]$Headers, [AllowNull()][AllowEmptyString()][string]$InstallId = '')
|    $h = if ($null -ne $Headers) { $Headers } else { @{} }
|    $iid = ConvertTo-SIInvardiaInstallId $InstallId
|    if ($iid) { $h['X-Invardia-Install-Id'] = $iid }
|    return $h
|}
|
|function Add-SIUplinkInstallId {
|    <#
|        PURE (sets one field). An IDENTIFIED uplink record with -FieldName (default InstallId, the name PIM 3.0.14 sends) =
|        -InstallId, lower-cased. Unchanged when the id is not a GUID, when the record is a setup report (Kind / kind 'setup'),
|        or when it is $null. The caller decides identified vs anonymous: an anonymous record is never passed here.
|    #>
|    param([AllowNull()][object]$Record, [AllowNull()][AllowEmptyString()][string]$InstallId = '', [string]$FieldName = 'InstallId')
|    if ($null -eq $Record) { return $Record }
|    $iid = ConvertTo-SIInvardiaInstallId $InstallId
|    if (-not $iid) { return $Record }
|    if ($Record -is [System.Collections.IDictionary]) {
|        foreach ($k in 'Kind', 'kind') { if ($Record.Contains($k) -and "$($Record[$k])" -eq 'setup') { return $Record } }
|        $Record[$FieldName] = $iid
|        return $Record
|    }
|    $kp = $Record.PSObject.Properties['Kind']
|    if ($kp -and "$($kp.Value)" -eq 'setup') { return $Record }
|    $Record | Add-Member -NotePropertyName $FieldName -NotePropertyValue $iid -Force
|    return $Record
|}
'@ }
$__siSupportFiles['engine/SI-FeatureCatalog.ps1'] = @{ Sha256 = '1313bf7e4404e75c99a4fb424b68453af1d0f95327314b438742b0dd7050d13a'; Text = @'
|#Requires -Version 5.1
|<#
|.SYNOPSIS
|    LIC-1 -- SecurityInsight's feature catalog and the one gate its engines call.
|
|.DESCRIPTION
|    The licence FORMAT, signature and validity rules are FRAMEWORK-level (sync/_AitLicense.ps1 -- one
|    implementation, every solution). This file owns only the half that is genuinely SecurityInsight's:
|    WHICH FEATURES ARE PAID, where an install's licence comes from, and what a refused feature does.
|
|    🔒 THE RULE THIS FILE EXISTS TO ENFORCE (operator, 2026-09-08):
|        "license is only needed if not free" / "so license req is not for all a req"
|    A FREE feature never touches the licence path at all -- Test-SIFeatureAvailable returns for a free
|    feature BEFORE any licence is loaded, so a missing, expired, corrupt or wrong-tenant licence cannot
|    affect anything free. Community users hold no licence and must never be able to notice licensing.
|
|    🔒 v3 EDITIONS (operator rulings 2026-09-29, SI #159):
|      * Pro = the ServiceNow connector, the CMDB in SQL and its connectors, governance (departments, governance mails,
|        the task digest). Everything else is the Community edition: profilers, tier classifier, cross-engine
|        correlation and the full asset properties (owner 2026-10-27, #750 (1)), every Risk Analysis report, the AI
|        summary, trend, all outputs, the generic CSV CMDB, VM and container hosting, Shodan, asset tagging (#750 (2)),
|        verification and data health (#750 (8)).
|      * ENFORCED from v3 launch -- SI Pro is PAID. This replaces the 2026-09-08 ship-OFF default on
|        purpose. There is deliberately no customer switch: the only config an install has is the
|        customer's own, and a switch there would be a free Pro edition. (-Enforce stays for tests.)
|      * THE DATABASE AND THE WEB APP ARE IN BOTH VERSIONS (owner 2026-10-18, #750 (a); #477, #480, #678): the settings
|        database ('settings-database') and the data backend ('data-backend' -- the data sync, the Risk Analysis store, the
|        CIs in SQL) are no longer paid. They are not in the catalog any more, so they are free by the rule below (their
|        call sites keep their gate call: a no-op for a free feature). The paid features of the database chain are named
|        instead: 'governance' (departments, governance mails, the task digest) and 'cmdb-connectors' (the CMDB in SQL).
|      * Delivered as the Key Vault secret 'SI-License' (the signed file as JSON or base64), read at runtime
|        on VM and container alike; a licence file in config\ is the fallback.
|
|    🔑 TWO GATES, DIFFERENT QUESTIONS (LIC-3). ring = WHEN a version reaches you; licence = WHETHER you may
|    run a feature. And a CAPABILITY is not a FEATURE: capabilities in solution.deploy.json are ring-gated
|    INSTALL units; features here are licence-gated BEHAVIOUR. A required capability may never be Pro.
|
|    🔑 THE VERIFIER IS LOADED FROM SI's OWN COPY (engine/_shared/AitLicense.ps1, byte-identical to
|    sync/_AitLicense.ps1 -- a test fails on drift). sync/ is not in a container image or the public mirror,
|    so the previous "search upward for sync/" found nothing there and would have refused every Pro feature.
|
|    🔒 THE EDITION DECIDES, NOT features[] (framework §12.6a LICENCE-FEATURES, SI #510; owner 2026-10-09: "but does that
|    mean we have to sign licenses when new features are released, that is not smart"). The signed licence names the
|    EDITION in its `sku`; THIS file maps edition -> features:
|      * a Pro edition (sku Pro / Pro-Business / Pro-DesignPartner / Trial / any Pro-*) = EVERY catalog entry with
|        Edition 'Pro', current and future -- a Pro licence issued before a feature existed already covers it;
|      * an MSP edition (sku naming MSP) = the Pro features + the entries with Edition 'MSP' (multi-tenant; none today);
|      * Pro Business vs Pro Enterprise differ by the signed `limits`, never by features;
|      * features[] is informational, and counts ONLY for an entry marked AddOn = $true (an explicit paid add-on, which
|        needs its own id in features[]; '*' does not cover an add-on). There are NO add-ons today.
|    A licence that is not valid / in grace, not bound to this tenant, or whose sku names no Pro edition (Community,
|    Core, empty) gives Community. The shared verifier (AitLicense.ps1) is unchanged: SI asks it for the status and the
|    tenant binding, and applies the edition rule here, at its own call site.
|
|    🔴 ABSENCE IS NOT REMEDIATION (working rule 4). A refused Pro engine SKIPS and says why; it never
|    publishes an empty result, and no close path acts on the absence of its output.
|#>
|
|# Azure access: plain REST, no PowerShell modules (engine/_shared/SI-AzRest.ps1).
|if (-not (Get-Command -Name Invoke-SIArm -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot '_shared/SI-AzRest.ps1') }
|
|Set-StrictMode -Off
|
|# ---------------------------------------------------------------------------
|# THE CATALOG. Everything not listed here is FREE -- the default is free, so a
|# feature can never become paid by omission or typo, only by a deliberate entry.
|#
|# 🪤 NAME THE CONNECTOR PRECISELY. SI's INBOUND CSV provider was called
|# `servicenow-cmdb` until v2.2.421, it is FREE, and ~510 report references depend on
|# it. A loosely worded "ServiceNow = Pro" would gate the free CSV importer.
|#
|# Edition = 'Pro' (every Pro edition has it) | 'MSP' (multi-tenant; the MSP edition only).
|# AddOn   = $true only for an explicit paid add-on that the licence must LIST in features[] (#510). None today.
|# ---------------------------------------------------------------------------
|$script:SIFeatureCatalog = @(
|    [pscustomobject]@{
|        Name        = 'servicenow-connector'
|        Edition     = 'Pro'
|        Built       = $true
|        Title       = 'The ServiceNow CMDB connector'   # short name for the one-line skip message customers see
|        Description = 'ServiceNow CMDB connector (match and create CIs, vulnerability close-loop). Distinct from the free inbound CMDB CSV import.'
|    }
|    # 'correlation' (cross-engine correlation and the full asset properties) is NOT here any more: it is in the Community
|    # edition (owner 2026-10-27, SI #750 (1) / #678 -- "data in, data correlation, ra + data out to excel are part of
|    # community"). Unknown = free, so every call site that still names it runs in both editions.
|    [pscustomobject]@{
|        Name        = 'governance'
|        Edition     = 'Pro'
|        Built       = $true
|        Title       = 'Departments, governance and follow-up tasks'
|        Description = 'Asset responsibility put to work: the department reports, the governance mails (exemptions, remediation flows, vendor escalation) and the daily task digest.'
|    }
|    [pscustomobject]@{
|        Name        = 'cmdb-connectors'
|        Edition     = 'Pro'
|        Built       = $true
|        Title       = 'The CMDB in SQL and its connectors'
|        Description = 'The CMDB kept in the SecurityInsight database: the SQL CMDB connector and the CMDB import. Distinct from the free inbound CMDB CSV file.'
|    }
|)
|
|function Get-SIFeatureCatalog {
|    <# .SYNOPSIS Every PAID feature SI knows about. Everything else is free by default. #>
|    [CmdletBinding()] param()
|    return @($script:SIFeatureCatalog)
|}
|
|function Test-SIFeatureIsPaid {
|    <#
|    .SYNOPSIS
|        PURE. Is this feature paid? Unknown names are FREE.
|    .DESCRIPTION
|        🔒 UNKNOWN => FREE, deliberately. Guessing the other way means a typo in a call site silently
|        gates a shipped free feature for every customer at once. A typo in a PAID call site costs an
|        ungated paid feature -- recoverable, and the wiring tests name every paid call site.
|    #>
|    [CmdletBinding()] param([Parameter(Mandatory)][string]$Feature)
|    foreach ($f in $script:SIFeatureCatalog) {
|        if ("$($f.Name)" -ieq "$Feature".Trim()) { return ("$($f.Edition)" -in @('Pro', 'MSP')) }
|    }
|    return $false
|}
|
|function Get-SILicenceEdition {
|    <#
|    .SYNOPSIS
|        PURE. The EDITION a licence's signed sku names: 'MSP' | 'Pro' | 'Community' (framework §12.6a, SI #510).
|    .DESCRIPTION
|        Reads only the sku -- not the status, the tenant or features[] (Test-SIFeatureAvailable checks those).
|        Pro = a sku that starts with 'Pro' or 'Trial' as a word: Pro, Pro-Business, Pro Enterprise, Pro-DesignPartner,
|        pro-single-tenant, Trial. MSP = a sku naming 'msp' as a word (Pro-MSP, pro-msp). Anything else -- Community,
|        the verifier's 'Core' for no licence, an empty sku -- is Community.
|    #>
|    param([AllowNull()]$License)
|    if ($null -eq $License) { return 'Community' }
|    $sku = "$($License.Sku)".Trim()
|    if ($sku -match '(?i)(^|[^a-z])msp([^a-z]|$)') { return 'MSP' }
|    if ($sku -match '(?i)^(pro|trial)([^a-z]|$)') { return 'Pro' }
|    return 'Community'
|}
|
|function Test-SILicenceCoversFeature {
|    <#
|    .SYNOPSIS
|        PURE. Does a licence that is ALREADY valid/grace and bound to this tenant cover this paid catalog entry?
|        Returns @{ Allowed; Reason }. The edition decides; features[] only for an add-on (#510).
|    #>
|    param([AllowNull()]$License, [Parameter(Mandatory)][object]$Entry)
|    $name = "$($Entry.Name)"
|    if ([bool]$Entry.AddOn) {
|        foreach ($f in @($License.Features | Where-Object { $_ })) {
|            if ("$f".Trim() -ieq $name) { return [pscustomobject]@{ Allowed = $true; Reason = "the licence lists the add-on '$name'" } }
|        }
|        return [pscustomobject]@{ Allowed = $false; Reason = "'$name' is an add-on and the licence does not list it" }
|    }
|    $ed = Get-SILicenceEdition -License $License
|    $need = if ("$($Entry.Edition)" -ieq 'MSP') { 'MSP' } else { 'Pro' }
|    if ($ed -eq 'MSP' -or ($need -eq 'Pro' -and $ed -eq 'Pro')) {
|        return [pscustomobject]@{ Allowed = $true; Reason = "the $ed edition covers '$name'" }
|    }
|    $skuText = "$($License.Sku)".Trim(); if (-not $skuText) { $skuText = 'none' }
|    if ($need -eq 'MSP' -and $ed -eq 'Pro') { return [pscustomobject]@{ Allowed = $false; Reason = "'$name' is part of the MSP edition; this licence is $skuText" } }
|    return [pscustomobject]@{ Allowed = $false; Reason = "the licence names no SecurityInsight Pro edition (sku $skuText)" }
|}
|
|function Get-SIFrameworkLicensePath {
|    <#
|    .SYNOPSIS
|        The framework licence verifier for this install: SI's own copy first, then sync/ upward.
|    .DESCRIPTION
|        Returns $null when neither exists rather than throwing -- a free feature must still run.
|    #>
|    [CmdletBinding()] param([string]$StartPath)
|    $own = [IO.Path]::Combine($PSScriptRoot, '_shared', 'AitLicense.ps1')
|    if (-not "$StartPath".Trim() -and (Test-Path -LiteralPath $own)) { return $own }
|    $p = if ("$StartPath".Trim()) { $StartPath } elseif ($PSScriptRoot) { $PSScriptRoot } else { (Get-Location).Path }
|    for ($i = 0; $i -lt 6; $i++) {
|        # [IO.Path]::Combine, not Join-Path: Join-Path throws on a missing drive.
|        $cand = [IO.Path]::Combine($p, 'sync', '_AitLicense.ps1')
|        if (Test-Path -LiteralPath $cand) { return $cand }
|        $parent = Split-Path -Parent $p
|        if (-not $parent -or $parent -eq $p) { break }
|        $p = $parent
|    }
|    return $null
|}
|
|function ConvertFrom-SILicenseText {
|    <# The secret holds the licence file as raw JSON or base64 of it. Returns the parsed document or $null. #>
|    param([AllowNull()][string]$Text)
|    if ([string]::IsNullOrWhiteSpace($Text)) { return $null }
|    $t = $Text.Trim()
|    if (-not $t.StartsWith('{')) {
|        try { $t = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($t)).Trim() } catch { return $null }
|    }
|    try { return ($t | ConvertFrom-Json -ErrorAction Stop) } catch { return $null }
|}
|
|function Get-SILicenseSecretText {
|    <# The SI-License secret, without the customer having to edit their config. Never throws. #>
|    if ($global:SI_License) { return [string]$global:SI_License }
|    # an internal install: the platform Key Vault (signed in by SecurityInsight itself -- auth/SI-PlatformConnect.ps1)
|    if ($global:Context -and $global:KV_HighPriv_KeyVaultName) {
|        try {
|            if (-not (Get-Command -Name Get-SIPlatformSecret -ErrorAction SilentlyContinue)) { . ([IO.Path]::Combine((Split-Path -Parent $PSScriptRoot), 'auth', 'SI-PlatformConnect.ps1')) }
|            return [string](Get-SIPlatformSecret -Context $global:Context -Name 'SI-License' -AsPlainText -ErrorAction Stop)
|        } catch { }
|    }
|    # The vault is resolved the way every other SI component resolves it (#173): SI_KeyVaultName, then the
|    # 2.2.x name SpnKeyVaultName, ... -- an upgraded install carrying only the older name was otherwise
|    # "unlicensed" while its licence sat in the vault it already uses for its SPN secret.
|    if (-not (Get-Command -Name Get-SIVaultName -ErrorAction SilentlyContinue)) {
|        $vaultHelper = [IO.Path]::Combine((Split-Path -Parent $PSScriptRoot), 'auth', 'Get-SIVaultName.ps1')
|        if (Test-Path -LiteralPath $vaultHelper) { . $vaultHelper }
|    }
|    $vault = $null
|    if (Get-Command -Name Get-SIVaultName -ErrorAction SilentlyContinue) { try { $vault = Get-SIVaultName -AllowMissing } catch { } }
|    elseif ($global:SI_KeyVaultName) { $vault = [string]$global:SI_KeyVaultName }
|    if ($vault) {
|        if (-not (Get-Command -Name Get-SIKvSecret -ErrorAction SilentlyContinue)) {
|            $kvHelper = [IO.Path]::Combine((Split-Path -Parent $PSScriptRoot), 'auth', 'Get-SIKvSecret.ps1')
|            if (Test-Path -LiteralPath $kvHelper) { . $kvHelper }
|        }
|        if (Get-Command -Name Get-SIKvSecret -ErrorAction SilentlyContinue) {
|            try { return [string](Get-SIKvSecret -VaultName $vault -SecretName 'SI-License') } catch { }
|        }
|    }
|    return $null
|}
|
|# Load the framework verifier ONCE, at file scope, so its functions outlive any one call. (Dot-sourcing it
|# inside a function defines them in that function's scope, and they vanish when it returns.) Loading the
|# verifier's CODE is not consulting a licence: a free feature still never reads one.
|$script:SIFrameworkLicensePath = Get-SIFrameworkLicensePath
|if ($script:SIFrameworkLicensePath) { . $script:SIFrameworkLicensePath }
|
|$script:SILicenseCache  = $null
|$script:SILicenseWarned = @{}
|
|# Framework LICENCE-DIMENSION (owner 2026-10-08): Pro has two dimensions, decided by the SIGNED licence -- Pro Business =
|# the payload carries a `limits` object (SecurityInsight reads `devices`), Pro Enterprise = no `limits`. Community has no
|# limits. A limit is a WARNING, never a stop: nothing here gates a feature or a run (the web app shows the banner).
|function ConvertTo-SILicenceLimits {
|    <#
|        PURE. The payload's `limits` value -> an ordered map name (lower-case) -> whole number, or $null when it is not an
|        object (absent / null / text / a number = no limits = Pro Enterprise). A value that is not a whole number is dropped,
|        never guessed; an empty object stays an empty map (the licence IS Business, without a SecurityInsight limit).
|    #>
|    param([AllowNull()]$Value)
|    if ($null -eq $Value -or $Value -isnot [System.Management.Automation.PSCustomObject]) { return $null }
|    $m = [ordered]@{}
|    foreach ($p in $Value.PSObject.Properties) {
|        $v = $p.Value
|        if (($v -is [int] -or $v -is [long]) -and $v -ge 0 -and $v -le [int]::MaxValue) { $m[$p.Name.ToLowerInvariant()] = [int]$v }
|    }
|    return $m
|}
|
|function Get-SILicenceLimitsOf {
|    <#
|        The limits of a VERIFIED licence, read ONLY from its signed payload bytes (payloadB64): a `limits` on the outer
|        document is not signed and is never read. $null for a licence that did not verify, or that names no limits.
|    #>
|    param([AllowNull()]$Document, [AllowNull()]$License)
|    if ($null -eq $Document -or $null -eq $License) { return $null }
|    if ("$($License.Status)" -notin @('Valid', 'Grace', 'NotYetValid', 'Expired')) { return $null }
|    try {
|        $p = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("$($Document.payloadB64)")) | ConvertFrom-Json -ErrorAction Stop
|        if ("$($p.licenseId)" -ne "$($License.LicenseId)") { return $null }
|        if ($p.PSObject.Properties.Name -contains 'limits') { return (ConvertTo-SILicenceLimits -Value $p.limits) }
|    } catch { }
|    return $null
|}
|
|function Get-SILicenceDimension {
|    <# PURE. 'Pro Business' | 'Pro Enterprise' | 'Community' for a licence: Pro while it is valid or in grace. #>
|    param([AllowNull()]$License)
|    if ($null -eq $License -or "$($License.Status)" -notin @('Valid', 'Grace')) { return 'Community' }
|    if ((Get-SILicenceEdition -License $License) -eq 'Community') { return 'Community' }   # #510: the sku names the edition
|    if ($License.PSObject.Properties['Limits'] -and $null -ne $License.Limits) { return 'Pro Business' }
|    return 'Pro Enterprise'
|}
|
|function Get-SILicense {
|    <#
|    .SYNOPSIS
|        This install's licence status (cached per process): Key Vault secret first, then config\.
|        Always a status object (Missing / Invalid / NotYetValid / Valid / Grace / Expired), never a throw.
|    #>
|    [CmdletBinding()]
|    param(
|        [AllowNull()][string]$SecretText,          # tests inject; absent = read the real sources
|        [AllowNull()][string]$LicenseDirectory,    # tests inject; absent = the solution's config\
|        [AllowNull()][string[]]$TrustedCertsB64,   # tests inject a throwaway signer
|        [AllowNull()][object]$Now,
|        [switch]$Refresh
|    )
|    $injected = $PSBoundParameters.ContainsKey('SecretText') -or $PSBoundParameters.ContainsKey('LicenseDirectory') -or
|                $PSBoundParameters.ContainsKey('TrustedCertsB64') -or $PSBoundParameters.ContainsKey('Now')
|    if ($script:SILicenseCache -and -not $Refresh -and -not $injected) { return $script:SILicenseCache }
|
|    if (-not (Get-Command -Name Resolve-AitLicenseStatus -ErrorAction SilentlyContinue)) {
|        return [pscustomobject]@{ Status = 'Missing'; Reason = 'the framework licence verifier is not installed'; Customer = ''; Features = @(); TenantIds = @(); Source = 'none'; Limits = $null }
|    }
|
|    $text = if ($PSBoundParameters.ContainsKey('SecretText')) { $SecretText } else { Get-SILicenseSecretText }
|    if (-not [string]::IsNullOrWhiteSpace($text)) {
|        $doc = ConvertFrom-SILicenseText -Text $text
|        $lic = Resolve-AitLicenseStatus -Document $doc -TrustedCertsB64 $TrustedCertsB64 -Now $Now
|        if ($null -eq $doc) { $lic.Status = 'Invalid'; $lic.Reason = 'the SI-License secret is neither licence JSON nor base64 of it' }
|        Add-Member -InputObject $lic -NotePropertyName Source -NotePropertyValue 'Key Vault secret SI-License' -Force
|        Add-Member -InputObject $lic -NotePropertyName Limits -NotePropertyValue (Get-SILicenceLimitsOf -Document $doc -License $lic) -Force
|    } else {
|        $dir = if ("$LicenseDirectory".Trim()) { $LicenseDirectory } else { [IO.Path]::Combine((Split-Path -Parent $PSScriptRoot), 'config') }
|        $lic = Get-AitLicense -Directory $dir -TrustedCertsB64 $TrustedCertsB64 -Now $Now
|        Add-Member -InputObject $lic -NotePropertyName Source -NotePropertyValue $(if ($lic.Path) { "file $($lic.Path)" } else { 'none' }) -Force
|        # the file is read again for its limits -- and verified again, so a file swapped in between gives none
|        $limits = $null
|        if ($lic.Path) {
|            try {
|                $fdoc = Get-Content -LiteralPath $lic.Path -Raw -Encoding UTF8 | ConvertFrom-Json -ErrorAction Stop
|                $again = Resolve-AitLicenseStatus -Document $fdoc -TrustedCertsB64 $TrustedCertsB64 -Now $Now
|                if ($again.Status -eq $lic.Status) { $limits = Get-SILicenceLimitsOf -Document $fdoc -License $again }
|            } catch { $limits = $null }
|        }
|        Add-Member -InputObject $lic -NotePropertyName Limits -NotePropertyValue $limits -Force
|    }
|    if (-not $injected) { $script:SILicenseCache = $lic }
|    return $lic
|}
|
|function Get-SIRunTenantId {
|    # #232 (operator: "validate license against the tenant so license can not be copied to other tenants" -- "must also
|    # work if customer use spn"). A MANAGED IDENTITY's token always comes from its home tenant, so the tenant is the
|    # 'tid' of the identity's own token (recorded by Get-SIManagedIdentityToken), never a configured value the customer
|    # controls. Unprovable = a value no licence names, so a tenant-bound licence fails CLOSED.
|    # An SPN's token is issued by the configured tenant, so for an SPN the configured tenant IS where the engine runs.
|    if ([bool]$global:SI_UseManagedIdentity) {
|        if (-not $global:SI_IdentityTokenTenantId -and (Get-Command -Name Get-SIManagedIdentityToken -ErrorAction SilentlyContinue)) {
|            try { $null = Get-SIManagedIdentityToken -Resource 'https://management.azure.com/' } catch { }
|        }
|        if ($global:SI_IdentityTokenTenantId) { return [string]$global:SI_IdentityTokenTenantId }
|        return 'unproven-managed-identity-tenant'
|    }
|    $t = @($global:SI_SPN_TenantId, $global:AzureTenantId, $global:TenantId) | Where-Object { $_ } | Select-Object -First 1
|    if (-not $t) { try { $t = [string](Get-SIAzContext -ErrorAction Stop).Tenant.Id } catch { } }
|    return [string]$t
|}
|
|function Test-SIFeatureAvailable {
|    <#
|    .SYNOPSIS
|        THE call-site gate. May this feature run? Returns @{ Allowed; Edition; Reason }.
|    .DESCRIPTION
|        🔒 ORDER IS THE CONTRACT, and it is asserted in tests:
|          1. FREE feature          -> allowed IMMEDIATELY. No licence is loaded, looked for, or consulted.
|          2. paid, -Enforce $false -> allowed (TESTS ONLY -- production has no such switch).
|          3. paid                  -> the framework verifier gives the status and the tenant binding (valid or
|                                      grace, bound to this tenant); then the EDITION the sku names decides
|                                      (§12.6a, #510): a Pro edition runs every Pro entry, current and future,
|                                      whatever features[] says. features[] counts only for an AddOn entry.
|        Grace runs, with one warning per feature per process.
|    #>
|    [CmdletBinding()]
|    param(
|        [Parameter(Mandatory)][string]$Feature,
|        [Parameter()][AllowNull()][string]$TenantId,
|        [Parameter()][AllowNull()][string]$LicenseDirectory,
|        [Parameter()][AllowNull()][object]$License,
|        [Parameter()][AllowNull()][object]$Enforce
|    )
|
|    # 1. FREE -- return before anything licence-shaped happens.
|    if (-not (Test-SIFeatureIsPaid -Feature $Feature)) {
|        return [pscustomobject]@{ Allowed = $true; Edition = 'Free'; Reason = "'$Feature' is a free feature -- no licence is required or consulted" }
|    }
|    if ($null -ne $Enforce -and -not [bool]$Enforce) {
|        return [pscustomobject]@{ Allowed = $true; Edition = 'Pro'; Reason = "enforcement is OFF for this call -- '$Feature' runs unlicensed" }
|    }
|
|    if ($null -eq $License) {
|        $License = if ("$LicenseDirectory".Trim()) { Get-SILicense -LicenseDirectory $LicenseDirectory -SecretText '' } else { Get-SILicense }
|    }
|    if (-not (Get-Command -Name Test-AitLicenseTenant -ErrorAction SilentlyContinue)) {
|        return [pscustomobject]@{ Allowed = $false; Edition = 'Pro'; Reason = "the framework licence verifier is not installed -- cannot establish entitlement for '$Feature'" }
|    }
|    if (-not "$TenantId".Trim()) { $TenantId = Get-SIRunTenantId }
|    # the verifier's status + tenant binding, then the edition (never features[] for an edition feature -- #510)
|    if ($null -eq $License -or "$($License.Status)" -notin @('Valid', 'Grace')) {
|        $st = if ($License) { "$($License.Status)" } else { 'Missing' }
|        $res = [pscustomobject]@{ Allowed = $false; Reason = "no entitlement: licence status is $st" }
|    } elseif (-not (Test-AitLicenseTenant -License $License -TenantId $TenantId)) {
|        $res = [pscustomobject]@{ Allowed = $false; Reason = "licence '$($License.Customer)' is not valid for tenant $TenantId" }
|    } else {
|        $entry = $script:SIFeatureCatalog | Where-Object { "$($_.Name)" -ieq "$Feature".Trim() } | Select-Object -First 1
|        $res = Test-SILicenceCoversFeature -License $License -Entry $entry
|    }
|    if ($res.Allowed -and "$($License.Status)" -eq 'Grace' -and -not $script:SILicenseWarned[$Feature]) {
|        $script:SILicenseWarned[$Feature] = $true
|        Write-Warning ("Your SecurityInsight Pro licence {0}. '{1}' keeps running until the grace period ends." -f $License.Reason, $Feature)
|    }
|    return [pscustomobject]@{ Allowed = [bool]$res.Allowed; Edition = 'Pro'; Reason = "$($res.Reason)" }
|}
|
|function Get-SIEdition {
|    <# 'Pro' when the licence entitles any paid EDITION feature for this tenant, else 'Community'. An add-on alone (#510)
|       does not make an install Pro. #>
|    param([AllowNull()][object]$License, [AllowNull()][string]$TenantId)
|    foreach ($f in @($script:SIFeatureCatalog | Where-Object { -not [bool]$_.AddOn })) {
|        if ((Test-SIFeatureAvailable -Feature $f.Name -License $License -TenantId $TenantId).Allowed) { return 'Pro' }
|    }
|    return 'Community'
|}
|
|function Assert-SIFeatureOrSkip {
|    <#
|    .SYNOPSIS
|        The one call a paid engine makes at its start. $true = run. $false = one plain line saying the feature
|        is part of SecurityInsight Pro and why it did not run; the engine then ends successfully WITHOUT
|        producing output, so nothing downstream reads an empty result as "everything was resolved".
|    #>
|    param([Parameter(Mandatory)][string]$Feature, [AllowNull()][string]$TenantId)
|    $r = Test-SIFeatureAvailable -Feature $Feature -TenantId $TenantId
|    # #277: a licence in its grace period, or an installed licence that does not let a Pro job run, is a guard trip
|    # (mail + telemetry, once per feature per process). No licence at all is the Community edition -- not a trip.
|    if ((Get-Command -Name Send-SIGuardEvent -ErrorAction SilentlyContinue) -and (Test-SIFeatureIsPaid -Feature $Feature)) {
|        if ($null -eq $script:SILicenseGuardSent) { $script:SILicenseGuardSent = @{} }
|        if (-not $script:SILicenseGuardSent.ContainsKey($Feature)) {
|            try {
|                $lic = Get-SILicense 3>$null
|                $st = if ($lic) { [string]$lic.Status } else { 'Missing' }
|                if ($r.Allowed -and $st -eq 'Grace') {
|                    $script:SILicenseGuardSent[$Feature] = $true
|                    $null = Send-SIGuardEvent -GuardId 'licence.state.grace' -Outcome 'warning' -Subject $Feature -Detail ('The SecurityInsight Pro licence {0}.' -f $lic.Reason)
|                } elseif (-not $r.Allowed -and $st -notin @('Missing', '')) {
|                    $script:SILicenseGuardSent[$Feature] = $true
|                    $null = Send-SIGuardEvent -GuardId 'licence.state.invalid' -Outcome 'refused' -Subject $Feature -Detail ('{0} did not run: {1}' -f $Feature, $r.Reason)
|                }
|            } catch { }
|        }
|    }
|    if ($r.Allowed) { return $true }
|    $entry = $script:SIFeatureCatalog | Where-Object { $_.Name -ieq $Feature } | Select-Object -First 1
|    $what = $null
|    if ($entry) { $what = $entry.Title; if (-not $what) { $what = $entry.Description } }
|    if (-not $what) { $what = $Feature }
|    Write-Host (" [INFO] {0} is part of SecurityInsight Pro and did not run ({1}). Nothing was changed or published; the previous results stay as they were." -f $what, $r.Reason)
|    return $false
|}
|
|function Test-SILicenseForInstall {
|    <#
|      PURE (#173). May this licence be INSTALLED? Checked by setup\Set-SILicense.ps1 before anything is written,
|      so a bad licence is refused at the desk instead of discovered as "Pro silently skipped" on the next run.
|        * the signature/dates must verify: Valid, Grace (renew now) or NotYetValid (starts later) -- never
|          Invalid / Expired / Missing;
|        * it must unlock something (#510, framework §12.6a): its sku names a Pro edition, or it lists an add-on
|          SecurityInsight has. features[] is informational for an edition licence, so a Pro licence with an empty or
|          old features[] installs; feature ids SecurityInsight does not have are a NOTE, never a refusal. (The first
|          licence issued granted 'SI.ServiceNow' / 'SI.Correlation' -- under the edition rule its sku Pro covers SI.)
|        * when it is bound to tenants and the tenant is known, this tenant must be one of them.
|      Returns @{ Ok; Problems; Notes; Edition; Summary }.
|    #>
|    param(
|        [Parameter(Mandatory)][object]$License,          # Get-SILicense / Resolve-AitLicenseStatus output
|        [AllowEmptyCollection()][string[]]$KnownFeatures = @(),
|        [AllowNull()][string]$TenantId
|    )
|    $problems = New-Object System.Collections.Generic.List[string]
|    $notes = New-Object System.Collections.Generic.List[string]
|    $st = "$($License.Status)"
|    if ($st -notin 'Valid', 'Grace', 'NotYetValid') { $problems.Add(("the licence does not verify: {0} ({1})" -f $st, $License.Reason)) }
|    $feats = @($License.Features | Where-Object { $_ } | ForEach-Object { "$_".Trim() })
|    $edition = Get-SILicenceEdition -License $License
|    $addOns = @($script:SIFeatureCatalog | Where-Object { [bool]$_.AddOn } | ForEach-Object { "$($_.Name)" })
|    $listedAddOns = @($feats | Where-Object { $addOns -contains $_ })
|    if ($edition -eq 'Community' -and -not $listedAddOns.Count) {
|        $skuText = "$($License.Sku)".Trim(); if (-not $skuText) { $skuText = 'none' }
|        $problems.Add(("the licence names no SecurityInsight Pro edition (sku {0}) and lists no add-on, so it unlocks nothing" -f $skuText))
|    }
|    $unknown = @($feats | Where-Object { $_ -ne '*' -and ($KnownFeatures -notcontains $_) })
|    if ($unknown.Count) { $notes.Add(("features[] names ids SecurityInsight does not have: {0} -- informational only, the edition decides" -f ($unknown -join ', '))) }
|    $ids = @($License.TenantIds | Where-Object { $_ })
|    if ($ids.Count -and "$TenantId".Trim() -and -not (@($ids | Where-Object { "$_".Trim() -ieq "$TenantId".Trim() }).Count)) {
|        $problems.Add(("it is bound to tenant(s) {0}, not to this tenant {1}" -f ($ids -join ', '), $TenantId))
|    }
|    $summary = "{0} -- {1}; edition: {2}; features: {3}; tenants: {4}" -f $License.Customer, $License.Reason, $edition, $(if ($feats.Count) { $feats -join ', ' } else { 'none listed' }), $(if ($ids.Count) { $ids -join ', ' } else { 'any' })
|    [pscustomobject]@{ Ok = ($problems.Count -eq 0); Problems = $problems.ToArray(); Notes = $notes.ToArray(); Edition = $edition; Summary = $summary }
|}
'@ }
$__siSupportFiles['auth/SI-PlatformConnect.ps1'] = @{ Sha256 = '2da078f5be28f13cdd78b27329c3e7d07ac19544dc3eabe9fe14c7ad53ae3d12'; Text = @'
|#Requires -Version 5.1
|<#
|    SecurityInsight -- sign in on an INTERNAL (AutomateIT platform) install with no PowerShell module.
|
|    The platform framework's own sign-in lives in a PowerShell module that uses the Az / Microsoft Graph modules.
|    SecurityInsight runs with no modules, so it signs in to the platform itself, over plain REST, reading exactly what
|    the framework reads and setting exactly what the framework sets:
|
|      1. bootstrap\platform-config.json  (TenantId, SubscriptionId, KeyVaultName, BootstrapAppId, BootstrapThumbprint,
|                                          BootstrapAuth = Auto | ManagedIdentity | Certificate)
|      2. the BOOTSTRAP identity (managed identity when the host has one and it works, else its certificate) reads the
|         platform Key Vault: Modern-AppId, Modern-Thumbprint (optional), Modern-Secret (only when the certificate path
|         cannot be used)
|      3. the run signs in as the MODERN identity: certificate when its thumbprint is in Key Vault AND the certificate is
|         installed and valid here, else the secret
|      4. the framework's public contract is populated -- $global:HighPriv_Modern_* , $global:AzureTenantId,
|         $global:KV_HighPriv_*, $global:AutomationFramework, $global:Context, and the SI_SPN_* / Spn* aliases -- so every
|         consumer of those globals keeps working unchanged.
|
|    Get-SIPlatformSecret reads one platform Key Vault secret as the signed-in identity. A configuration file written for
|    the framework calls Get-PlatformSecret; when the framework's module is not loaded (it never is, in SecurityInsight)
|    a compatible Get-PlatformSecret is published that does the same over REST.
|
|    PS 5.1 safe (no ?. / ??, no RSA.ImportFromPem); works on pwsh 7. Internal installs only -- never in the Community
|    edition's code path (it runs only when bootstrap\platform-config.json exists).
|#>
|
|# NO Set-StrictMode HERE -- a dot-sourced file that sets it leaks into the caller's scope.
|
|if (-not (Get-Command -Name Invoke-SIArm -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot '../engine/_shared/SI-AzRest.ps1') }
|# The managed-identity helper is loaded only when the bootstrap sign-in is a managed identity (inside Connect-SIPlatform):
|# the run's entry point owns that helper, and a run that never uses it never loads it.
|$__siCertFile = Join-Path $PSScriptRoot 'Find-SICertificate.ps1'
|if ((Test-Path -LiteralPath $__siCertFile) -and -not (Get-Command -Name Get-SICertificateFromStore -ErrorAction SilentlyContinue)) { . $__siCertFile }
|
|function Test-SIPlatformConfigDisabled {
|    <# True when this process must not use the machine's AutomateIT platform configuration: SI_PLATFORM_CONFIG = off
|       (the guided install sets it for its run -- live 2026-10-06 on the development machine the platform's subscription was used). #>
|    [string]([Environment]::GetEnvironmentVariable('SI_PLATFORM_CONFIG')) -match '^(?i)(off|0|false|no|disabled)$'
|}
|
|function Find-SIPlatformConfigPath {
|    <# bootstrap\platform-config.json, walking up from -Start (the framework's own rule). $null when there is none. #>
|    param([string]$Start = $PSScriptRoot)
|    # SI_PLATFORM_CONFIG=off: this run must not use the machine's platform (the guided install sets it for its run)
|    if (Test-SIPlatformConfigDisabled) { return $null }
|    $cur = $Start
|    while ($cur) {
|        $p = [System.IO.Path]::Combine($cur, 'bootstrap', 'platform-config.json')
|        if (Test-Path -LiteralPath $p) { return $p }
|        $parent = Split-Path -Parent $cur
|        if (-not $parent -or $parent -eq $cur) { break }
|        $cur = $parent
|    }
|    return $null
|}
|
|function Read-SIPlatformConfig {
|    <# The platform configuration; TenantId, SubscriptionId and KeyVaultName are required (as the framework requires). #>
|    param([Parameter(Mandatory)][string]$Path)
|    if (-not (Test-Path -LiteralPath $Path)) { throw ("The platform configuration was not found at {0}." -f $Path) }
|    try { $cfg = Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json }
|    catch { throw ("The platform configuration {0} could not be read: {1}" -f $Path, $_.Exception.Message) }
|    $missing = @('TenantId', 'SubscriptionId', 'KeyVaultName' | Where-Object { -not $cfg.PSObject.Properties[$_] -or [string]::IsNullOrWhiteSpace([string]$cfg.$_) })
|    if ($missing.Count) { throw ("The platform configuration {0} is missing: {1}." -f $Path, ($missing -join ', ')) }
|    return $cfg
|}
|
|function Test-SIPlatformManagedIdentityHost {
|    <# Does this host have a managed-identity endpoint (a container, an Azure Arc server, or an Azure VM whose metadata
|       endpoint answers within 3 seconds -- the framework's Auto probe)? -Probe is a test seam. #>
|    param([scriptblock]$Probe)
|    if ([Environment]::GetEnvironmentVariable('IDENTITY_ENDPOINT')) { return $true }
|    if ($Probe) { return [bool](& $Probe) }
|    try {
|        $req = [System.Net.HttpWebRequest]::Create('http://169.254.169.254/metadata/instance?api-version=2021-02-01')
|        $req.Method = 'GET'; $req.Timeout = 3000; $req.ReadWriteTimeout = 3000
|        $req.Headers['Metadata'] = 'true'
|        $resp = $req.GetResponse(); $resp.Close(); return $true
|    } catch {
|        $we = $_.Exception
|        while ($we -and -not ($we -is [System.Net.WebException])) { $we = $we.InnerException }
|        if ($we -and $we.Response) { try { $we.Response.Close() } catch { }; return $true }   # it answered: an endpoint exists
|        return $false
|    }
|}
|
|function Get-SIPlatformBootstrapAuths {
|    <# PURE (given -HasManagedIdentity). The bootstrap sign-ins to try, in order: BootstrapAuth = ManagedIdentity ->
|       the managed identity, then the certificate when the configuration has one (the framework's cross-tenant
|       fall-through); Certificate -> the certificate; Auto -> the managed identity when the host has one, then the
|       certificate. #>
|    param([Parameter(Mandatory)]$Config, [bool]$HasManagedIdentity)
|    $mode = if ($Config.PSObject.Properties['BootstrapAuth'] -and [string]$Config.BootstrapAuth) { [string]$Config.BootstrapAuth } else { 'Auto' }
|    $appId = [string]$Config.BootstrapAppId; $thumb = ([string]$Config.BootstrapThumbprint) -replace '\s', ''
|    $cert = if ($appId -and $thumb) { @{ Mode = 'Certificate'; AppId = $appId; TenantId = [string]$Config.TenantId; Thumbprint = $thumb } } else { $null }
|    $mi = @{ Mode = 'ManagedIdentity'; ClientId = '' }
|    $out = New-Object System.Collections.Generic.List[hashtable]
|    switch -Regex ($mode) {
|        '^(?i)managedidentity$' { [void]$out.Add($mi); if ($cert) { [void]$out.Add($cert) } }
|        '^(?i)certificate$'     { if ($cert) { [void]$out.Add($cert) } }
|        default                 { if ($HasManagedIdentity) { [void]$out.Add($mi) }; if ($cert) { [void]$out.Add($cert) } }
|    }
|    if ($out.Count -eq 0) {
|        throw ("The platform configuration names no usable bootstrap sign-in (BootstrapAuth = {0}; BootstrapAppId / BootstrapThumbprint {1})." -f $mode, $(if ($cert) { 'set' } else { 'missing' }))
|    }
|    return $out.ToArray()
|}
|
|function Test-SIPlatformCertificateUsable {
|    <# Is the certificate with -Thumbprint installed (LocalMachine\My or CurrentUser\My, read through X509Store -- no
|       Cert: drive needed), with its private key, and valid today? -Find is a test seam returning what
|       Get-SICertificateFromStore returns ({ Certificate; StoreLocation }) or a bare certificate, or $null.
|       #395: Get-SICertificateFromStore returns a WRAPPER. Reading NotAfter on the wrapper gave $null, `$null -le (Get-Date)`
|       is true, and every certificate -- valid until 2028 -- was reported EXPIRED: every internal install fell back to a
|       client secret it does not have, and every run failed. The certificate's own properties are read, never the wrapper's. #>
|    param([string]$Thumbprint, [scriptblock]$Find)
|    $tp = ([string]$Thumbprint).Trim() -replace '\s', ''
|    if (-not $tp) { return $false }
|    $found = if ($Find) { & $Find $tp } else { Get-SICertificateFromStore -Thumbprint $tp }
|    if (-not $found) { return $false }
|    $c = $found
|    if ($found.PSObject.Properties['Certificate'] -and $null -ne $found.Certificate) { $c = $found.Certificate }
|    if (-not ($c -is [System.Security.Cryptography.X509Certificates.X509Certificate2])) {
|        Write-Warning ("The platform certificate {0} could not be read from the certificate store. The client secret is used instead." -f $tp)
|        return $false
|    }
|    if (-not $c.HasPrivateKey) {
|        Write-Warning ("The platform certificate {0} is installed WITHOUT its private key, so it cannot sign in. Install it with the key; the client secret is used meanwhile." -f $tp)
|        return $false
|    }
|    $now = Get-Date
|    if ($c.NotAfter -le $now) {
|        Write-Warning ("The platform certificate {0} is installed but EXPIRED on {1:yyyy-MM-dd}. Renew it; the client secret is used meanwhile." -f $tp, $c.NotAfter)
|        return $false
|    }
|    if ($c.NotBefore -gt $now) {
|        Write-Warning ("The platform certificate {0} is installed but not valid before {1:yyyy-MM-dd}. The client secret is used meanwhile." -f $tp, $c.NotBefore)
|        return $false
|    }
|    return $true
|}
|
|function Read-SIPlatformBootstrapSecret {
|    <# One platform Key Vault secret read as the BOOTSTRAP identity; $null when it does not exist. #>
|    param([Parameter(Mandatory)][string]$VaultName, [Parameter(Mandatory)][string]$Name, [Parameter(Mandatory)][hashtable]$Auth)
|    $v = Get-SIKeyVaultSecretValue -VaultName $VaultName -Name $Name -Auth $Auth
|    if ($null -eq $v) { return $null }
|    return ([string]$v).Trim()
|}
|
|function New-SIPlatformContext {
|    <# The context object the framework's consumers read ($global:Context): Tenant.Id / SubscriptionId / KeyVaultName,
|       Providers.Secret = 'KeyVault', Host.Kind = 'VM'. #>
|    param([string]$TenantId, [string]$SubscriptionId, [string]$KeyVaultName)
|    [pscustomobject]@{
|        Schema       = 'AutomateIT.Context/1'
|        StartedUtc   = [datetime]::UtcNow
|        Host         = [pscustomobject]@{ Kind = 'VM'; ComputerName = $env:COMPUTERNAME; UserName = $env:USERNAME; PSVersion = $PSVersionTable.PSVersion.ToString() }
|        Tenant       = [pscustomobject]@{ Id = $TenantId; SubscriptionId = $SubscriptionId; KeyVaultName = $KeyVaultName }
|        Providers    = [pscustomobject]@{ Secret = 'KeyVault'; State = 'None'; Log = 'Stdout' }
|        SignedInBy   = 'SecurityInsight'
|    }
|}
|
|function Connect-SIPlatform {
|    <#
|        Sign in as the platform's Modern identity (see this file's header) and populate the framework's public globals.
|        -ConfigPath: bootstrap\platform-config.json (default: found walking up from -Start). Returns the context, or $null
|        when there is no platform configuration (a Community / standalone install -- nothing to do, as the framework's own
|        back-compat entry point did). Throws when the configuration exists but the sign-in cannot be completed.
|    #>
|    [CmdletBinding()]
|    param([string]$ConfigPath, [string]$Start = $PSScriptRoot, [scriptblock]$ProbeManagedIdentity)
|    if (Test-SIPlatformConfigDisabled) { return $null }
|    if (-not $ConfigPath) { $ConfigPath = Find-SIPlatformConfigPath -Start $Start }
|    if (-not $ConfigPath -or -not (Test-Path -LiteralPath $ConfigPath)) { return $null }
|    $cfg = Read-SIPlatformConfig -Path $ConfigPath
|    $tenantId = [string]$cfg.TenantId; $subId = [string]$cfg.SubscriptionId; $kv = [string]$cfg.KeyVaultName
|
|    $hasMi = Test-SIPlatformManagedIdentityHost -Probe $ProbeManagedIdentity
|    $candidates = @(Get-SIPlatformBootstrapAuths -Config $cfg -HasManagedIdentity $hasMi)
|    $boot = $null; $appId = $null; $errors = New-Object System.Collections.Generic.List[string]
|    $miFile = Join-Path (Split-Path -Parent $MyInvocation.MyCommand.ScriptBlock.File) 'SI-ManagedIdentity.ps1'
|    foreach ($a in $candidates) {
|        if ($a.Mode -eq 'ManagedIdentity' -and -not (Get-Command -Name Get-SIManagedIdentityToken -ErrorAction SilentlyContinue) -and (Test-Path -LiteralPath $miFile)) {
|            . $miFile
|        }
|        try {
|            $appId = Read-SIPlatformBootstrapSecret -VaultName $kv -Name 'Modern-AppId' -Auth $a
|            $boot = $a
|            break
|        } catch { [void]$errors.Add(('{0}: {1}' -f $a.Mode, $_.Exception.Message)) }
|    }
|    if (-not $boot) { throw ("The platform Key Vault '{0}' could not be read with the bootstrap sign-in ({1})." -f $kv, ($errors -join ' | ')) }
|    if ([string]::IsNullOrWhiteSpace($appId)) { throw ("The platform Key Vault '{0}' has no 'Modern-AppId' secret (or it is empty)." -f $kv) }
|
|    $thumb = $null
|    try { $thumb = Read-SIPlatformBootstrapSecret -VaultName $kv -Name 'Modern-Thumbprint' -Auth $boot } catch { Write-Verbose ("Modern-Thumbprint not read: {0}" -f $_.Exception.Message) }
|    $certOk = $false
|    if ($thumb) {
|        $certOk = Test-SIPlatformCertificateUsable -Thumbprint $thumb
|        if (-not $certOk) { Write-Warning ("Key Vault names the platform certificate {0}, but it is not installed (and valid) on this host; signing in with the client secret instead." -f $thumb) }
|    }
|    $secret = $null
|    if (-not $certOk) {
|        $secret = Read-SIPlatformBootstrapSecret -VaultName $kv -Name 'Modern-Secret' -Auth $boot
|        if ([string]::IsNullOrWhiteSpace($secret)) {
|            throw ("The platform identity cannot sign in on this host: no usable certificate, and the platform Key Vault '{0}' has no 'Modern-Secret'." -f $kv)
|        }
|    }
|
|    # sign in as the Modern identity (recorded; each REST call mints its token when it needs one)
|    if ($certOk) {
|        $null = Connect-SIAzAccount -ServicePrincipal -ApplicationId $appId -CertificateThumbprint $thumb -Tenant $tenantId -Subscription $subId
|    } else {
|        $cred = New-Object System.Management.Automation.PSCredential ($appId, ([System.Net.NetworkCredential]::new('', $secret).SecurePassword))
|        $null = Connect-SIAzAccount -ServicePrincipal -Credential $cred -Tenant $tenantId -Subscription $subId
|    }
|
|    $ctx = New-SIPlatformContext -TenantId $tenantId -SubscriptionId $subId -KeyVaultName $kv
|    # the framework's public contract -- the same names and values its own sign-in sets
|    $global:Context                                     = $ctx
|    $global:AzureTenantId                               = $tenantId
|    $global:HighPriv_Modern_ApplicationID_Azure         = $appId
|    $global:HighPriv_Modern_Secret_Azure                = $secret   # $null when the certificate signs in
|    $global:HighPriv_Modern_AuthMethod                  = $(if ($certOk) { 'Cert' } else { 'Secret' })
|    $global:HighPriv_Modern_CertificateThumbprint_Azure = $(if ($certOk) { $thumb } else { $null })
|    $global:KV_HighPriv_KeyVaultName                    = $kv
|    $global:KV_HighPriv_SubscriptionId                  = $subId
|    $global:AutomationFramework                         = $true
|    $global:SI_SPN_TenantId                             = $tenantId
|    $global:SI_SPN_AppId                                = $appId
|    $global:SI_SPN_Secret                               = $secret
|    $global:SpnTenantId                                 = $tenantId
|    $global:SpnClientId                                 = $appId
|    $global:SpnClientSecret                             = $secret
|    return $ctx
|}
|
|function Get-SIPlatformSecret {
|    <# One secret from the platform Key Vault ($global:Context / $global:KV_HighPriv_KeyVaultName), read as the signed-in
|       identity. THROWS when it does not exist (the framework's rule: a caller treats an optional secret as optional
|       with try/catch). -AsPlainText returns a string, else a SecureString. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$Name, [switch]$AsPlainText, $Context)
|    if (-not $Context) { $Context = $global:Context }
|    $kv = $null
|    if ($Context -and $Context.PSObject.Properties['Tenant'] -and $Context.Tenant) { $kv = [string]$Context.Tenant.KeyVaultName }
|    if (-not $kv) { $kv = [string]$global:KV_HighPriv_KeyVaultName }
|    if (-not $kv) { throw ("Get-PlatformSecret: no platform Key Vault is known in this run, so secret '{0}' was not found." -f $Name) }
|    $v = Get-SIKeyVaultSecretValue -VaultName $kv -Name $Name
|    if ($null -eq $v) { throw ("Get-PlatformSecret: secret '{0}' not found in vault '{1}'." -f $Name, $kv) }
|    if ($AsPlainText) { return [string]$v }
|    return [System.Net.NetworkCredential]::new('', [string]$v).SecurePassword
|}
|
|# A configuration file written for the framework calls Get-PlatformSecret -Context $global:Context -Name ... . The
|# framework's module is never loaded by SecurityInsight, so the same call is answered here, over REST. Published
|# globally and self-loading: configuration files are dot-sourced inside the launcher's configuration function, where
|# this file's other functions may not be visible.
|$global:SI_PlatformConnectFile = Join-Path $PSScriptRoot 'SI-PlatformConnect.ps1'
|if (-not (Get-Command -Name Get-PlatformSecret -ErrorAction SilentlyContinue)) {
|    function global:Get-PlatformSecret {
|        [CmdletBinding()]
|        param($Context, [Parameter(Mandatory)][string]$Name, [switch]$AsPlainText)
|        if (-not (Get-Command -Name Get-SIPlatformSecret -ErrorAction SilentlyContinue)) { . $global:SI_PlatformConnectFile }
|        Get-SIPlatformSecret -Name $Name -AsPlainText:$AsPlainText -Context $Context
|    }
|}
'@ }
$__siSupportFiles['auth/Get-SIVaultName.ps1'] = @{ Sha256 = 'ebb0663efe664c2aa019929e268a8c6d5ec287211ac9e0a35a1b82f7d95422c8'; Text = @'
|#Requires -Version 5.1
|<#
|    SI -- ONE KEY VAULT, RESOLVED IN ONE PLACE.
|
|    🔒 Operator, 2026-08-31: *"use the keyvault for the SI instance, so it is captured into one SI
|    keyvault."*
|
|    🔴 THE PROBLEM THIS FIXES IS THAT SI ALREADY NAMED ITS VAULT THREE WAYS, and each caller picked
|    one:
|      $global:SI_KeyVaultName        written by the Config Wizard (Write-SICustomConfig.ps1)
|      $global:SpnKeyVaultName        the name the config reference shows (Connect-SIAzCli read it; deleted)
|      $env:SI_DIAGNOSTICS_VAULT      the diagnostics scripts' own resolution
|    A customer who set one and not the others got a component that could not find the vault -- and the
|    failure surfaces as "no credential", which reads like a permissions problem and is not. Three
|    spellings of one fact is the same defect class as `EgNodeId`/`ExposureGraphNodeId`, which cost a
|    silent correlation split.
|
|    ✅ SO: every SI component resolves the vault through HERE, in a fixed order, and any one of the
|    three globals being set is enough. Nothing is renamed and no existing install breaks -- the
|    resolution simply stops depending on which name the customer happened to use.
|
|    ⛔ NO DEFAULT, EVER. There is no sensible fallback vault name: guessing one would send a secret
|    read at some other customer's vault, or at an internal one. Unresolved is an error with a message
|    that says what to set.
|
|    NO Set-StrictMode here -- it leaks into the caller's scope (measured 2026-08-12).
|#>
|
|function Get-SIVaultName {
|    <#
|        The SI Key Vault for this install.
|
|          -VaultName  an explicit override, which always wins (a CLI parameter, a test)
|
|        Order after that: SI_KeyVaultName -> SpnKeyVaultName -> SI_DIAGNOSTICS_VAULT env ->
|        SI_DiagnosticsVaultName. The diagnostics names come LAST on purpose: they exist so a
|        developer's sandbox vault is reachable, and they must never take precedence over a customer's
|        configured vault on a real run.
|    #>
|    [CmdletBinding()]
|    param(
|        [Parameter()][string]$VaultName,
|        # Return $null instead of throwing. For callers that treat "no vault" as a supported state --
|        # the CMDB connector's plan-only path needs no secrets at all.
|        [Parameter()][switch]$AllowMissing
|    )
|
|    if (-not [string]::IsNullOrWhiteSpace($VaultName))                       { return $VaultName.Trim() }
|    if (-not [string]::IsNullOrWhiteSpace([string]$global:SI_KeyVaultName))  { return ([string]$global:SI_KeyVaultName).Trim() }
|    if (-not [string]::IsNullOrWhiteSpace([string]$global:SpnKeyVaultName))  { return ([string]$global:SpnKeyVaultName).Trim() }
|    if (-not [string]::IsNullOrWhiteSpace([string]$env:SI_DIAGNOSTICS_VAULT)){ return ([string]$env:SI_DIAGNOSTICS_VAULT).Trim() }
|    if (-not [string]::IsNullOrWhiteSpace([string]$global:SI_DiagnosticsVaultName)) { return ([string]$global:SI_DiagnosticsVaultName).Trim() }
|
|    if ($AllowMissing) { return $null }
|    throw ('SI: no Key Vault is configured. Set $global:SI_KeyVaultName in config\SecurityInsight.custom.ps1 ' +
|           '(the Config Wizard writes it for you). $global:SpnKeyVaultName is also accepted for installs ' +
|           'that predate that name. The vault holds the SPN secret and any integration credentials, and ' +
|           'there is deliberately no default -- guessing a vault name would send a secret read somewhere ' +
|           'it does not belong.')
|}
|
|# ---------------------------------------------------------------------------------------------------
|# THE SERVICENOW SECRET NAMES, in one place so the connector and the diagnostics cannot drift.
|#
|# 🔑 CANONICAL NAMES FIRST, LEGACY SECOND. The diagnostics scripts seeded `servicenow-pdi-*` while the
|# connector was being proven against a developer instance. Those keep working -- an operator should not
|# have to re-seed a vault to pick up a rename -- but a new install gets the `SI-ServiceNow-*` names,
|# which say which SOLUTION owns them in a vault that may hold secrets for several.
|# ---------------------------------------------------------------------------------------------------
|$script:SIServiceNowSecretNames = [ordered]@{
|    Instance = @('SI-ServiceNow-Instance', 'servicenow-pdi-instance')
|    User     = @('SI-ServiceNow-User',     'servicenow-pdi-user')
|    Password = @('SI-ServiceNow-Password', 'servicenow-pdi-password')
|}
|
|function Get-SIServiceNowSecretName {
|    <# The candidate secret names for one part, canonical first. #>
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][ValidateSet('Instance','User','Password')][string]$Part)
|    @($script:SIServiceNowSecretNames[$Part])
|}
|
|function Get-SIServiceNowCredentialFromVault {
|    <#
|        The ServiceNow instance URL and integration credential, from the ONE SI vault.
|
|        Returns @{ Instance; Credential; InstanceSecretName } or $null when the vault holds none of
|        them -- which is a supported state for a plan-only run and must not throw there.
|
|        🪤 A PARTIAL SET IS AN ERROR, NOT A DEGRADED SUCCESS. An instance URL with no credential would
|        build a connection that fails on the first call with a 401, which reads like a permissions
|        problem at the customer's end. Say which secret is missing instead.
|    #>
|    [CmdletBinding()]
|    param(
|        [Parameter()][string]$VaultName,
|        # Injectable so this is testable without a vault. Takes (vault, secretName), returns the value
|        # or $null.
|        [Parameter()][scriptblock]$Reader
|    )
|
|    $vault = Get-SIVaultName -VaultName $VaultName -AllowMissing
|    if ([string]::IsNullOrWhiteSpace($vault)) { return $null }
|
|    if (-not $Reader) {
|        $Reader = {
|            param($v, $n)
|            try { Get-SIKvSecret -VaultName $v -SecretName $n } catch { $null }
|        }
|    }
|
|    $found = @{}
|    foreach ($part in @('Instance','User','Password')) {
|        foreach ($name in (Get-SIServiceNowSecretName -Part $part)) {
|            $val = & $Reader $vault $name
|            if (-not [string]::IsNullOrWhiteSpace([string]$val)) {
|                $found[$part] = [string]$val
|                if ($part -eq 'Instance') { $found['InstanceSecretName'] = $name }
|                break
|            }
|        }
|    }
|
|    if ($found.Count -eq 0) { return $null }
|
|    $missing = @()
|    foreach ($part in @('Instance','User','Password')) { if (-not $found.ContainsKey($part)) { $missing += $part } }
|    if ($missing.Count -gt 0) {
|        throw ("SI: the ServiceNow credential in Key Vault '{0}' is INCOMPLETE -- missing {1}. Expected {2}. " -f `
|                $vault, ($missing -join ', '),
|                (@('Instance','User','Password') | ForEach-Object { (Get-SIServiceNowSecretName -Part $_)[0] }) -join ' / ') +
|              'A partial set would build a connection that fails on the first call with a 401, which reads like a permissions problem at the customer end.'
|    }
|
|    $sec = New-Object System.Security.SecureString
|    foreach ($ch in ([string]$found['Password']).ToCharArray()) { $sec.AppendChar($ch) }
|    $sec.MakeReadOnly()
|
|    [pscustomobject]@{
|        Instance           = [string]$found['Instance']
|        Credential         = (New-Object System.Management.Automation.PSCredential([string]$found['User'], $sec))
|        InstanceSecretName = [string]$found['InstanceSecretName']
|        VaultName          = $vault
|    }
|}
'@ }
$__siSupportFiles['auth/Get-SIKvSecret.ps1'] = @{ Sha256 = '0072740691d0711931706bdd1e2b18434a4d090557226e5b0a3a496d6f3715ec'; Text = @'
|#Requires -Version 5.1
|<#
|    Get-SIKvSecret -- runtime KV secret fetch for SecurityInsight engines.
|
|    Designed to be called from config/SecurityInsight.custom.ps1 at config-
|    load time so high-value secrets (Storage account keys, Shodan API key,
|    Azure OpenAI key) live ONLY in Key Vault and are pulled fresh into
|    in-memory globals on every launcher run -- never persisted to disk.
|
|    Auth strategy (in order) -- plain REST, no PowerShell module:
|      1. The run's own sign-in (what the launcher recorded with Connect-SIAzAccount, else the configured
|         SPN certificate / secret)
|      2. Otherwise a Managed Identity: user-assigned via $global:SI_ManagedIdentityClientId /
|         SI_KvMiClientId / SI_UAMI_ClientId when set, else the system-assigned one (typical internal VM)
|
|    Returns the secret as a plain string. Caller assigns it to a $global:
|    variable that the engines read.
|
|    Example use in config/SecurityInsight.custom.ps1:
|        . "$PSScriptRoot\..\auth\Get-SIKvSecret.ps1"
|        $kv = '<your-key-vault-name>'
|        $global:SI_Shodan_ApiKey = Get-SIKvSecret -VaultName $kv -SecretName 'SI-Shodan-ApiKey'
|        $global:OpenAI_apiKey    = Get-SIKvSecret -VaultName $kv -SecretName 'OpenAI-ApiKey'
|
|    Storage needs no secret: it is reached with the signed-in identity's Storage
|    Blob/Table/Queue Data Contributor roles.
|
|    Notes
|    -----
|    * PS 5.1 safe (no -AsPlainText switch which is PS 7+).
|    * No PowerShell module needed: the secret is read over REST (engine/_shared/SI-AzRest.ps1).
|    * No fallback to plaintext globals -- this helper is opt-in. If the
|      customer prefers plaintext, just don't call it.
|    * Returns $null (NOT throws) when the secret doesn't exist OR the
|      caller lacks Get-Secret RBAC -- engines will throw their own missing-
|      value error which is more actionable than a KV stack trace.
|#>
|
|# Azure access: plain REST, no PowerShell modules (engine/_shared/SI-AzRest.ps1).
|if (-not (Get-Command -Name Invoke-SIArm -ErrorAction SilentlyContinue)) { . (Join-Path $PSScriptRoot '../engine/_shared/SI-AzRest.ps1') }
|
|function Get-SIKvSecret {
|    [CmdletBinding()]
|    param(
|        [Parameter(Mandatory)][string]$VaultName,
|        [Parameter(Mandatory)][string]$SecretName
|    )
|
|    # ---- 1. Make sure a sign-in is known (recorded; the token is minted over REST on the read) ----
|    $ctx = Get-SIAzContext -ErrorAction SilentlyContinue
|    if (-not $ctx) {
|        # Try managed identity first (system-assigned, then user-assigned via global)
|        try {
|            # #222: the install's one managed-identity client id; SI_KvMiClientId is the older name.
|            $kvMi = if ($global:SI_ManagedIdentityClientId) { [string]$global:SI_ManagedIdentityClientId }
|                    elseif ($global:SI_KvMiClientId) { [string]$global:SI_KvMiClientId }
|                    else { [string]$global:SI_UAMI_ClientId }
|            if ($kvMi) {
|                Connect-SIAzAccount -Identity -AccountId $kvMi -WarningAction SilentlyContinue -ErrorAction Stop | Out-Null
|            } else {
|                Connect-SIAzAccount -Identity -WarningAction SilentlyContinue -ErrorAction Stop | Out-Null
|            }
|        } catch {
|            throw "Get-SIKvSecret: no sign-in is configured and the managed identity could not be used. Either run on an Azure VM with a managed identity assigned, or configure the SecurityInsight sign-in before loading custom.ps1. Inner: $($_.Exception.Message)"
|        }
|    }
|
|    # ---- 2. Pull the secret ----
|    try {
|        $sec = Get-SIAzKeyVaultSecret -VaultName $VaultName -Name $SecretName -ErrorAction Stop
|    } catch {
|        Write-Warning ("Get-SIKvSecret: failed to read '{0}' from KV '{1}': {2}" -f $SecretName, $VaultName, $_.Exception.Message)
|        return $null
|    }
|    if (-not $sec) { return $null }
|
|    # PS 5.1: convert SecureString -> plain text via NetworkCredential
|    return [System.Net.NetworkCredential]::new('', $sec.SecretValue).Password
|}
'@ }
$__siSupportFiles['engine/_shared/AitLicense.ps1'] = @{ Sha256 = 'b430fd4a5f8850e5ef0439b66c4b1f2e6798f0f5a563a2c195d15c1ec0e357f3'; Text = @'
|#Requires -Version 5.1
|<#
|.SYNOPSIS
|    LIC-1 -- the FRAMEWORK licence verifier. One implementation, every solution.
|
|.DESCRIPTION
|    The licence FORMAT is framework-wide by design: a customer holding one file for two
|    products must get identical semantics from both. LIC-1 therefore rules out the obvious
|    shortcut -- "Not chosen: copying PIM's verifier into SI ... two verifiers would drift
|    into two meanings of the same file" -- and LIC-3 places the verifier here, "beside
|    sync/_AitRings.ps1 as shared code that PIM and SI both call, with each solution keeping
|    only its own feature list."
|
|    So this file owns VERIFICATION. It deliberately owns nothing else:
|
|      here (framework)     : signature, validity window, grace, tenant binding, feature match
|      per solution         : the feature CATALOG, and what a gated feature does when refused
|
|    File format, as emitted by TOOLS/New-AitLicense.ps1:
|      { "product": "...", "payloadB64": "<b64 payload JSON>", "signature": "<b64 RSA sig>" }
|      payload: { licenseId, customer, sku, features[], tenantIds[], validFrom, validTo, graceDays }
|
|    Signature is RSA-SHA256 / PKCS#1 over the RAW PAYLOAD BYTES -- verified against the exact
|    payloadB64 bytes, never a re-serialised object, so JSON canonicalisation can never change
|    the answer.
|
|    🔒 OFFLINE. No activation, no call-home, no endpoint. Customers on locked-down automation
|    servers need nothing but the file. Only the PUBLIC certificate is embedded; the private key
|    never leaves the development machine.
|
|    🪤 SIGNED != FOUND (LIC-1 first issuance, 2026-09-05). The crypto half of a migration can
|    land while the DISCOVERY half does not, and the symptom -- Status=Missing -- is EXACTLY the
|    quiet resting state of an unlicensed install. The failure mode of a licensing system is
|    indistinguishable from its correct idle state, so discovery is treated as a first-class
|    concern here and tested on its own.
|
|.NOTES
|    PS 5.1: the certificate is loaded from raw bytes (X509Certificate2) and RSA comes via
|    RSACertificateExtensions. NOT RSA.ImportFromPem -- that is .NET Core 3.0+ / PS 7 only and
|    would break every customer engine, which run on 5.1.
|#>
|
|Set-StrictMode -Off
|
|# Public certificate of the framework licensing signer, CN=AutomateIT-Licensing-Service.
|# PUBLIC half only. Byte-identical to the copy PIM embeds, so a licence issued by
|# TOOLS/New-AitLicense.ps1 verifies the same under either until PIM migrates onto this file.
|$script:AitLicenseSignerCertB64 = 'MIIFFzCCAv+gAwIBAgIQNY8l3/KZOoxF7K1nXIXwazANBgkqhkiG9w0BAQsFADAnMSUwIwYDVQQDDBxBdXRvbWF0ZUlULUxpY2Vuc2luZy1TZXJ2aWNlMB4XDTI2MDgxMTEzMDY0NloXDTQ2MDgxMTEzMTE0NlowJzElMCMGA1UEAwwcQXV0b21hdGVJVC1MaWNlbnNpbmctU2VydmljZTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBALuth8WywLfudbaoZ6eR570apvs5LXzOeGfl5Z14z6Nl6DQgvwMLXG/8lZEHOCKsHWVtEnjZOZigsh4c16owJVhuW67OgY0Iy6OjmfeXzu+kcTICSdZ+Qj3ecsGp1Cz6Xo1AjYbgIORdqUBncy4BAuA1bxH0E+V+1zT+ltEk840xpLdWde+m7W8q7BrG9klh+xQl8xJTjeliyV0JN2mvBjI0JwB9t9vL2/luMWWtHp752/ZG4Icd9u6HyqSR/xEmlZIjkZwI7LEPLTICXV1iA3c3nFUEHkLhLlpDW6EQn3cip0Sijr7SVWEBH1fCA8vCo+PxIEgJc3RXaeRhqD4UOwPJIziHtrpy8+9L15zrhXnhIGZv2mUAHKiamUIOmKl9vj31vFp/vJx1chE0XA358T09HGu0jKgSbbC4afKQPKf3v+BHPU42T/xIOPMxDJWuFqKvr4anL7P5PEkTjycBRCkXnIPC5PlrXR/ZZz4oit4WKhbdzONYwb8CKnsF2Z9IVL9yviVJxAIr7kiGqRme9+H0t5A+hzAydxdFMQnop+R8Q02a0sei9WrdtCbwLempVVrXIS6N4hh5kvLqMouDi62b0h645UNk2cWahDIZWTKd/MYdlcdrtRt5muy2LOasHByVxUrZKwH7IetCmv+Kkm1BfMF6Fvi1Jh2Qgz4bo5XJAgMBAAGjPzA9MA4GA1UdDwEB/wQEAwIHgDAMBgNVHRMBAf8EAjAAMB0GA1UdDgQWBBT+IiWP1iqSIwaRLiV1somJAQ+ELjANBgkqhkiG9w0BAQsFAAOCAgEAFiDfl7nhDNIywkCZgu9iw0RtJUyJqiq8y+fXomucqowAQZKPhkpuHftZZjtDe09WM35TqjRgL7hqmJiEgqPlRrAv78FjE41RwMcANN2PVCrdcMcuDVdRbS40rObpp0B6+uVUiWY4+8MW6G8Wv+7CIBUEP8ypo3BhxQJZLpyJDKLNiPqnTVKOmYXe7BivfVz63F2Pg2dNXic1poQ7S6JTi/8FM4AV2Ge/zVQF+LaiIuBDJX3JjHnKXxNf1Zhk8PF6DeWaVSNyXtjESlaUfsz0U2Ue87UUZ8ELIuqjHTpG66HPInblBZme6VvR13n5QxmnvjPXdtmXAJzDzCf+76labSGQu9fMFxUoKwjAwT9vHrdFw8JEStappW7urXj+Oafp1wVafJOXzjd9utr8WT3AhaPeqMx3FYH20e2b7QNCI3owtm0ogHRg36neahe78PikiMe15AUpD3+BD6pKeLV7tsExeXZjxDxhFUSpScD0TrCOUEJdKL2Cfx8rM3ceISSiTTYmuJmU7fznQ122A6GNW58mpSk8miPYb3MzbLW0JFPRrEDiyT8dW1M9s98DL+7VR0z2QxgxhNMKyrVgBM7YgQtbtPLz26NBqAQsqG50rOdn7XmprzvnTmnb+r2PUQuqb6rCTAQFTJ3MjH7BviP3GkwJyvzMZ+S6OnUAGB2Fn3Y='
|
|# LIC-4 (operator 2026-10-03): the Invardia licence signer, CN=Invardia-Licensing (thumbprint BA65E6AA62128EBE89A743722E404980F6D2878D,
|# RSA 4096, valid to 2036-10-03). PUBLIC half only. Trusted ALONGSIDE the AutomateIT signer above -- never instead of it -- so
|# every licence already issued keeps verifying, and Invardia switches its signer only after this release is rolled out.
|# Byte-identical to the copy PIM embeds (engine/_shared/PIM-License.ps1) and to SI's copy of this file.
|$script:AitLicenseInvardiaCertB64 = 'MIIFQDCCAyigAwIBAgIQXXs1IY0ZQE2MwtugYutXwDANBgkqhkiG9w0BAQsFADAdMRswGQYDVQQDExJJbnZhcmRpYS1MaWNlbnNpbmcwHhcNMjYxMDAzMTY1NDMxWhcNMzYxMDAzMTcwNDMxWjAdMRswGQYDVQQDExJJbnZhcmRpYS1MaWNlbnNpbmcwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCn9X21WYLer9r3ojq9lCP3eGV5YK8UMHoyyGT/q8carwQK+ztBRweKAgHyg8rr67utZ1zZBDRei64T/63nXGZpC666efzNZjIU+Og7vtO0bTNjQm/yVD/Q4KFZachYbE5orU+99HQcgRrcwnmmltyazyun2MV2CTk2nUDeMX5IIFD/1yIT8SLNFa6b6Gy4Ms/TIlc4u3lEH3zjbTSF+phSrbv7J6ytz5Eq1ahRkKHWcdBoF9GJo2ynWP0vTGHWvvjNdeVpXP1rkGnLt9MAQj2Us/2XiTgZzf26QLNiXX9YeJeUA9IVdPWczJav+YYkcICyG4ynwhPCudI6S2iDeu8jyL54gfVT871/+RFebzKHq9teY2vB0aGsbaW9VOmV5dDQ2mVfQLFTkNd1ByeZKv9tR0vPfaiZCza+DedApF2LfoAa7Y34pb9WHGRJFAPVmG2WMSsTY90Y0VBYrktF4g4q712W2ZdQc+QIxtvP5nsz6bk1QBvJ1Hcsr/euiysxmkFxcl3NH7WM1EKzdzUaYDJpysoE9e0jkjdJpb9bNNmSE7V9IMTk7r/XOiYJ+8qOALTgwUIEyOLi/hfOihJDRn31aJ6aPvzCEYikueJV5oALrDxquiXbPi8z10aMuXLL4hfi6B7U0qo2kOTPQ9Qh/cJFVkV9pEXjtY+NwwI9EtxgaQIDAQABo3wwejAOBgNVHQ8BAf8EBAMCB4AwCQYDVR0TBAIwADAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwHwYDVR0jBBgwFoAUuZzWkYh3hkE0oJH42LneYVKXIzowHQYDVR0OBBYEFLmc1pGId4ZBNKCR+Ni53mFSlyM6MA0GCSqGSIb3DQEBCwUAA4ICAQCluVZnotzEyS5ux+4hMuz9mOfpSJCNg5nkS8XxIHySiE2AEjVT4ZFEyykZUFoROv5clLBkO5icvDDRBitkeKHvioZruRPtVGy0fs0VxJ4VMcOU/i5cVdJXBQeyUFE8o//4+7FXZp10ToVNv/drjdO7adcNHRVjsddm2mXPNyHmE07ErV6eInPj+r0/1dogPBW1knF+T53RTwT2O0Ppe5qK0QEdBfo5sf4nvjg7ONNXYlW38SzXGLsXy6TZphRWqxLq7u31HAwujQGy9syO+TPIzusH1WHkCsvjDDRXNI8iYhKcS2wq/P/O6O4Ebt/PFN0hxyzyuYx4kreXKKhqrfsEMDxzMUQNnUEjFgU4/4atLVJpBvoDmb/MuQDIzlhxz8obAJi5BuxyjyemR9jg6XMIE2IAhe1v+MN0ZY58tbZR3t5rF30tp541NRaJfn4DBpqNmAIFyDQMdM2FogkFoOV+Mo0IBmGzV/jyv/2z+sre1P5MncLP2qZhfFmu595gWnNoOsMdUZmEWMkbISMGvGzfpPRF3IBan+fymCZSsKNB00E3W50Sh/t2sopEYc3eSwpu6bhvPUgB2ZKU6KN49Al4Pf41uldHVY0aVVp+kpLmRntDFzkTNXUG4OWOwF5gHuGY8jIrwDR7pCPSNzDWrUf857O6DyWEsHXERWg5OPLNUg=='
|
|# Every trusted signer, in the order they are tried (a licence is valid if ANY of them verifies it).
|$script:AitLicenseTrustedCertsB64 = @($script:AitLicenseSignerCertB64, $script:AitLicenseInvardiaCertB64)
|
|# Extensions a licence may use, MOST SPECIFIC FIRST. A solution-specific file wins a tie so an
|# existing per-solution licence keeps precedence over a framework-wide one in the same folder.
|$script:AitLicenseExtensions = @('.pimlicense', '.silicense', '.aitlicense')
|
|<#
|.SYNOPSIS
|    PURE. Verify an RSA-SHA256/PKCS#1 signature over raw payload bytes.
|
|.DESCRIPTION
|    Returns $true only on a genuine match. Every failure path -- malformed certificate,
|    unusable key, bad signature -- returns $false rather than throwing, because a verifier
|    that throws on a tampered file turns "refuse this licence" into "crash the engine".
|#>
|function Test-AitLicenseSignature {
|    [CmdletBinding()]
|    param(
|        [Parameter(Mandatory)][byte[]]$PayloadBytes,
|        [Parameter(Mandatory)][byte[]]$SignatureBytes,
|        [Parameter(Mandatory)][string]$PublicCertB64
|    )
|    try {
|        $certBytes = [Convert]::FromBase64String($PublicCertB64)
|        $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(, $certBytes)
|        $rsa  = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPublicKey($cert)
|        if (-not $rsa) { return $false }
|        return $rsa.VerifyData(
|            $PayloadBytes,
|            $SignatureBytes,
|            [System.Security.Cryptography.HashAlgorithmName]::SHA256,
|            [System.Security.Cryptography.RSASignaturePadding]::Pkcs1)
|    } catch { return $false }
|}
|
|<#
|.SYNOPSIS
|    PURE. Turn a licence document + a clock into a status. No disk, no network.
|
|.DESCRIPTION
|    Split out from any file handling deliberately: this is where every rule that matters
|    lives, so it must be testable without writing a file. `Get-AitLicense` is the thin
|    impure wrapper that finds a file and calls this.
|
|.PARAMETER Document
|    The parsed licence object ({ payloadB64, signature }).
|
|.PARAMETER TrustedCertsB64
|    Accepted signers, in order. A caller mid-migration passes its legacy key as a second
|    entry so anything already issued keeps verifying -- there is no cutover and no reissue.
|
|.PARAMETER Now
|    Injected clock. A licence verifier whose tests cannot control time can only be tested
|    on the day the fixtures happen to be valid.
|
|.OUTPUTS
|    Status: Missing | Invalid | NotYetValid | Valid | Grace | Expired
|    Core is NEVER affected by any of them -- see Test-AitLicenseFeature.
|#>
|function Resolve-AitLicenseStatus {
|    [CmdletBinding()]
|    param(
|        [Parameter()][AllowNull()][object]$Document,
|        [Parameter()][AllowNull()][string[]]$TrustedCertsB64,
|        [Parameter()][AllowNull()][object]$Now
|    )
|
|    $result = [pscustomobject]@{
|        Status     = 'Missing'; Reason = 'no licence document supplied'
|        Customer   = ''; Sku = 'Core'; LicenseId = ''
|        Features   = @(); TenantIds = @()
|        ValidFrom  = $null; ValidTo = $null; GraceUntil = $null
|    }
|    if ($null -eq $Document) { return $result }
|
|    $today = if ($Now) { ([datetime]$Now).Date } else { (Get-Date).Date }
|    $certs = @($TrustedCertsB64 | Where-Object { $_ })
|    if (-not $certs.Count) { $certs = @($script:AitLicenseTrustedCertsB64) }
|
|    try {
|        if (-not $Document.payloadB64 -or -not $Document.signature) {
|            throw "not an AutomateIT licence (payloadB64/signature missing)"
|        }
|        $payloadBytes = [Convert]::FromBase64String("$($Document.payloadB64)")
|        $sigBytes     = [Convert]::FromBase64String("$($Document.signature)")
|
|        # Try every trusted signer. Order matters only for speed -- a licence is valid if ANY
|        # trusted key verifies it, which is what makes a signer migration a non-event.
|        $ok = $false
|        foreach ($c in $certs) {
|            if (Test-AitLicenseSignature -PayloadBytes $payloadBytes -SignatureBytes $sigBytes -PublicCertB64 $c) { $ok = $true; break }
|        }
|        if (-not $ok) {
|            $result.Status = 'Invalid'
|            $result.Reason = 'signature verification FAILED (file tampered, or not issued by a trusted AutomateIT licensing key)'
|            return $result
|        }
|
|        $p = [System.Text.Encoding]::UTF8.GetString($payloadBytes) | ConvertFrom-Json
|        $result.Customer  = "$($p.customer)"
|        $result.Sku       = "$($p.sku)"
|        $result.LicenseId = "$($p.licenseId)"
|        $result.Features  = @($p.features  | Where-Object { $_ })
|        $result.TenantIds = @($p.tenantIds | Where-Object { $_ })
|        # InvariantCulture, always. On da-DK "08/27/2026" parses as day 8 of month 27 and throws;
|        # the same locale bug already ate a promotedUtc stamp once (RING-7).
|        $result.ValidFrom = [datetime]::Parse("$($p.validFrom)", [System.Globalization.CultureInfo]::InvariantCulture).Date
|        $result.ValidTo   = [datetime]::Parse("$($p.validTo)",   [System.Globalization.CultureInfo]::InvariantCulture).Date
|
|        $graceDays = 30
|        if ($p.PSObject.Properties.Name -contains 'graceDays' -and "$($p.graceDays)" -match '^\d+$') { $graceDays = [int]$p.graceDays }
|        $result.GraceUntil = $result.ValidTo.AddDays($graceDays)
|
|        if     ($today -lt $result.ValidFrom)  { $result.Status = 'NotYetValid'; $result.Reason = "licence starts $($result.ValidFrom.ToString('yyyy-MM-dd'))" }
|        elseif ($today -le $result.ValidTo)    { $result.Status = 'Valid';       $result.Reason = "valid until $($result.ValidTo.ToString('yyyy-MM-dd'))" }
|        elseif ($today -le $result.GraceUntil) { $result.Status = 'Grace';       $result.Reason = "EXPIRED $($result.ValidTo.ToString('yyyy-MM-dd')) -- grace until $($result.GraceUntil.ToString('yyyy-MM-dd')), renew now" }
|        else                                   { $result.Status = 'Expired';     $result.Reason = "expired $($result.ValidTo.ToString('yyyy-MM-dd')) (grace ended $($result.GraceUntil.ToString('yyyy-MM-dd')))" }
|    } catch {
|        $result.Status = 'Invalid'
|        $result.Reason = "licence could not be read: $($_.Exception.Message)"
|    }
|    return $result
|}
|
|<#
|.SYNOPSIS
|    PURE. Is this licence bound to the tenant we are actually running against?
|
|.DESCRIPTION
|    An EMPTY or absent tenantIds list means "any tenant" -- that is the deliberate shape for
|    a site licence. A non-empty list binds, and the binding is the Entra tenant GUID.
|
|    🔒 A licence that names other tenants is NOT a licence for this one. That is the whole
|    point of binding, and it is why LIC-2 refuses to let a per-tenant licence be baked into a
|    build context shared by three tenants' images.
|#>
|function Test-AitLicenseTenant {
|    [CmdletBinding()]
|    param(
|        [Parameter()][AllowNull()][object]$License,
|        [Parameter()][AllowNull()][string]$TenantId
|    )
|    if ($null -eq $License) { return $false }
|    $ids = @($License.TenantIds | Where-Object { $_ })
|    # LIC anti-copy (operator 2026-10-03): a licence that names NO tenant is valid in NO tenant -- it used to be valid in
|    # every tenant, which made a copied file work anywhere. Every licence ever issued names its tenant(s).
|    if (-not $ids.Count) { return $false }
|    if (-not "$TenantId".Trim()) { return $false }      # bound, but we do not know who we are
|    foreach ($i in $ids) { if ("$i".Trim() -ieq "$TenantId".Trim()) { return $true } }
|    return $false
|}
|
|<#
|.SYNOPSIS
|    PURE. May this feature run?
|
|.DESCRIPTION
|    🔒 THE INVARIANT (LIC-1): a REQUIRED capability must never be Pro, and Core is never
|    affected by licence state. So this answers only for features a catalog has declared Pro;
|    everything else is free and must never be routed through here.
|
|    Grace counts as entitled -- that is what a grace window is for. Expired and Invalid do not.
|    '*' in the feature list means every Pro feature, which is how a site licence is expressed.
|
|.PARAMETER Enforce
|    🔒 ENFORCEMENT SHIPS OFF (LIC-1). With -Enforce absent, this returns $true with a reason
|    saying so: every feature behaves as though licensed, with no nag. That is what makes it
|    safe to issue licences to all ~30 customers and populate the registry BEFORE anything is
|    gated -- the rollout and the enforcement are separate events, and only the second one can
|    break somebody.
|#>
|function Test-AitLicenseFeature {
|    [CmdletBinding()]
|    param(
|        [Parameter()][AllowNull()][object]$License,
|        [Parameter(Mandatory)][string]$Feature,
|        [Parameter()][AllowNull()][string]$TenantId,
|        [switch]$Enforce
|    )
|
|    if (-not $Enforce) {
|        return [pscustomobject]@{ Allowed = $true; Reason = 'enforcement is OFF -- every feature runs (LIC-1 default posture)' }
|    }
|    if ($null -eq $License -or $License.Status -notin @('Valid', 'Grace')) {
|        $st = if ($License) { "$($License.Status)" } else { 'Missing' }
|        return [pscustomobject]@{ Allowed = $false; Reason = "no entitlement: licence status is $st" }
|    }
|    if (-not (Test-AitLicenseTenant -License $License -TenantId $TenantId)) {
|        return [pscustomobject]@{ Allowed = $false; Reason = "licence '$($License.Customer)' is not valid for tenant $TenantId" }
|    }
|    $feats = @($License.Features | Where-Object { $_ })
|    if ($feats -contains '*')       { return [pscustomobject]@{ Allowed = $true; Reason = "site licence ('*') covers '$Feature'" } }
|    foreach ($f in $feats) { if ("$f".Trim() -ieq "$Feature".Trim()) { return [pscustomobject]@{ Allowed = $true; Reason = "licensed for '$Feature'" } } }
|    return [pscustomobject]@{ Allowed = $false; Reason = "licence does not include feature '$Feature'" }
|}
|
|<#
|.SYNOPSIS
|    Find a licence file in a directory. IMPURE (disk), and separated for exactly that reason.
|
|.DESCRIPTION
|    🪤 THIS FUNCTION IS WHY LIC-1's FIRST ISSUANCE FAILED. The issuer wrote
|    `<customer>.aitlicense` while discovery globbed `*.pimlicense` only, so a correctly signed
|    licence reported Status=Missing -- indistinguishable from having no licence at all.
|    Accept EVERY known extension, most specific first.
|#>
|function Find-AitLicenseFile {
|    [CmdletBinding()]
|    param([Parameter(Mandatory)][string]$Directory)
|
|    if (-not (Test-Path -LiteralPath $Directory)) { return $null }
|    $rank = @{}
|    for ($i = 0; $i -lt $script:AitLicenseExtensions.Count; $i++) { $rank[$script:AitLicenseExtensions[$i]] = $i }
|
|    $f = Get-ChildItem -LiteralPath $Directory -File -ErrorAction SilentlyContinue |
|             Where-Object { $script:AitLicenseExtensions -contains $_.Extension.ToLowerInvariant() } |
|             Sort-Object @{ Expression = { $rank[$_.Extension.ToLowerInvariant()] } }, Name |
|             Select-Object -First 1
|    if ($f) { return $f.FullName }
|    return $null
|}
|
|<#
|.SYNOPSIS
|    Load + verify a licence. The thin impure wrapper over Resolve-AitLicenseStatus.
|
|.PARAMETER Path
|    A specific licence file. Wins over -Directory, and is what tests use.
|
|.PARAMETER Directory
|    Where to look when no -Path is given.
|#>
|function Get-AitLicense {
|    [CmdletBinding()]
|    param(
|        [Parameter()][AllowNull()][string]$Path,
|        [Parameter()][AllowNull()][string]$Directory,
|        [Parameter()][AllowNull()][string[]]$TrustedCertsB64,
|        [Parameter()][AllowNull()][object]$Now
|    )
|
|    $file = if ("$Path".Trim()) { $Path } elseif ("$Directory".Trim()) { Find-AitLicenseFile -Directory $Directory } else { $null }
|
|    if (-not $file -or -not (Test-Path -LiteralPath $file)) {
|        $r = Resolve-AitLicenseStatus -Document $null -TrustedCertsB64 $TrustedCertsB64 -Now $Now
|        $r.Reason = 'no .pimlicense / .silicense / .aitlicense file found'
|        Add-Member -InputObject $r -NotePropertyName Path -NotePropertyValue '' -Force
|        return $r
|    }
|
|    $doc = $null
|    try { $doc = Get-Content -LiteralPath $file -Raw -Encoding UTF8 | ConvertFrom-Json } catch { $doc = $null }
|    $res = Resolve-AitLicenseStatus -Document $doc -TrustedCertsB64 $TrustedCertsB64 -Now $Now
|    if ($null -eq $doc) { $res.Status = 'Invalid'; $res.Reason = 'licence file is not readable JSON' }
|    Add-Member -InputObject $res -NotePropertyName Path -NotePropertyValue $file -Force
|    return $res
|}
'@ }
$__siSupportFiles['engine/_shared/SI-OutboundTrust.ps1'] = @{ Sha256 = '34fe997008df9445c117d2c98cdf791cb808bf4acc3277a0543851b01d290217'; Text = @'
|#Requires -Version 5.1
|<#
|    SECURITYINSIGHT -- WHERE A CREDENTIAL MAY GO. PURE checks, each returning '' (allowed) or the reason in plain words.
|    The engine uses them where it sends a token, a key or the install's own credential; a value one of them refuses is left
|    out of the run and said (a warning), never the end of the run. The web app checks the same rules when a person saves a
|    setting (pro-management/src/SI.Management.Web/Settings/OutboundHostPolicy.cs).
|
|      Test-SIAzureSqlHost            the SQL server the engine sends its Azure SQL access token to: an Azure SQL host
|      Test-SITelemetryEndpointHost   the uplink the install key goes to: https, invardia.com or a subdomain of it
|      Test-SIHttpsSameOrigin         a connector's request or next page: https, the same host and port as its own base address
|      Test-SISqlDatabaseName         a database name, never a connection-string fragment
|      New-SISqlConnectionString      the Azure SQL connection string, built (never formatted) from the server and database
|
|    Strict-mode safe; PS 5.1 and 7.
|#>
|
|function Get-SIAzureSqlHostSuffixes { @('.database.windows.net', '.database.usgovcloudapi.net', '.database.chinacloudapi.cn', '.database.cloudapi.de') }
|
|function Get-SISqlServerHostName {
|    <# PURE. 'tcp:<host>,<port>' / '<host>,<port>' / '<host>' -> '<host>' (lower case). #>
|    param([AllowEmptyString()][string]$Server = '')
|    $h = "$Server".Trim()
|    if ($h.StartsWith('tcp:', [StringComparison]::OrdinalIgnoreCase)) { $h = $h.Substring(4) }
|    $c = $h.IndexOf(','); if ($c -ge 0) { $h = $h.Substring(0, $c) }
|    $h.Trim().ToLowerInvariant()
|}
|
|function Test-SIAzureSqlHost {
|    <# PURE. '' = -Server is an Azure SQL server (public or sovereign cloud) the engine's SQL access token may go to. #>
|    param([AllowEmptyString()][string]$Server = '')
|    $h = Get-SISqlServerHostName -Server $Server
|    if (-not $h) { return 'no SQL server is named' }
|    if ($h -notmatch '^[a-z0-9.-]+$') { return ("'{0}' is not a SQL server name" -f "$Server".Trim()) }
|    foreach ($s in (Get-SIAzureSqlHostSuffixes)) { if ($h.EndsWith($s) -and $h.Length -gt $s.Length) { return '' } }
|    ("'{0}' is not an Azure SQL server (<name>.database.windows.net)" -f $h)
|}
|
|function Test-SISqlDatabaseName {
|    <# PURE. '' = -Database is a database name (1-128 characters, no ; = quote bracket brace or control character). #>
|    param([AllowEmptyString()][string]$Database = '')
|    $d = "$Database".Trim()
|    if (-not $d) { return 'no database is named' }
|    if ($d.Length -gt 128 -or $d -match '[;=''"\[\]{}\x00-\x1f]') { return ("'{0}' is not a database name" -f $d) }
|    ''
|}
|
|function New-SISqlConnectionString {
|    <#
|        PURE. The connection string for an Azure SQL database with an Entra token: built with SqlConnectionStringBuilder, so a
|        server or database value is always ONE value (a ';' in it can never add a keyword). Encrypted, the certificate checked.
|    #>
|    param([Parameter(Mandatory)][string]$Server, [Parameter(Mandatory)][string]$Database, [int]$ConnectTimeoutSec = 30)
|    $csb = New-Object System.Data.SqlClient.SqlConnectionStringBuilder
|    $csb['Data Source'] = ('tcp:{0},1433' -f (Get-SISqlServerHostName -Server $Server))
|    $csb['Initial Catalog'] = "$Database".Trim()
|    $csb['Encrypt'] = $true; $csb['TrustServerCertificate'] = $false; $csb['Connect Timeout'] = $ConnectTimeoutSec
|    $csb.ConnectionString
|}
|
|function Test-SITelemetryEndpointHost {
|    <# PURE. '' = -Endpoint is Invardia's own https address (invardia.com or a subdomain) -- the only place the install key goes. #>
|    param([AllowEmptyString()][string]$Endpoint = '')
|    $e = "$Endpoint".Trim()
|    if (-not $e) { return 'no endpoint is set' }
|    $u = $null
|    if (-not [Uri]::TryCreate($e, [UriKind]::Absolute, [ref]$u)) { return ("'{0}' is not an address" -f $e) }
|    if ($u.Scheme -ne 'https') { return ("'{0}' is not https" -f $e) }
|    if ($u.UserInfo) { return ("'{0}' carries a user name" -f $u.Host) }
|    $h = $u.Host.ToLowerInvariant()
|    if ($h -eq 'invardia.com' -or $h.EndsWith('.invardia.com')) { return '' }
|    ("'{0}' is not an Invardia address" -f $u.Host)
|}
|
|function Test-SIHttpsSameOrigin {
|    <# PURE. '' = -Url is https with the same host and port as -BaseUrl (which must be https itself). #>
|    param([AllowEmptyString()][string]$Url = '', [AllowEmptyString()][string]$BaseUrl = '')
|    $b = $null; $u = $null
|    if (-not [Uri]::TryCreate("$BaseUrl".Trim(), [UriKind]::Absolute, [ref]$b) -or $b.Scheme -ne 'https') { return 'the connector''s base address is not an https address' }
|    if (-not [Uri]::TryCreate("$Url".Trim(), [UriKind]::Absolute, [ref]$u)) { return ("'{0}' is not an address" -f $Url) }
|    if ($u.Scheme -ne 'https') { return ("'{0}' is not https" -f $u.GetLeftPart([UriPartial]::Authority)) }
|    if ($u.UserInfo) { return ("'{0}' carries a user name" -f $u.Host) }
|    if (-not [string]::Equals($u.Host, $b.Host, [StringComparison]::OrdinalIgnoreCase) -or $u.Port -ne $b.Port) {
|        return ("'{0}' is not the connector's own host ({1})" -f $u.Authority, $b.Authority)
|    }
|    ''
|}
'@ }

# ---- the runner (release/Build-SISupportScripts.ps1) ----------------------------------------------------------------
$__siSupportDir = [IO.Path]::Combine([IO.Path]::GetTempPath(), ('securityinsight-support-' + [guid]::NewGuid().ToString('N').Substring(0, 12)))
$__siSupportWritten = New-Object System.Collections.Generic.List[string]
$__siSupportSha = [System.Security.Cryptography.SHA256]::Create()
try {
    foreach ($__k in @($__siSupportFiles.Keys)) {
        $__lines = ($__siSupportFiles[$__k].Text -replace "`r", '') -split "`n"
        $__body = (@($__lines | ForEach-Object { if ($_.StartsWith('|')) { $_.Substring(1) } else { $_ } }) -join "`r`n") + "`r`n"
        $__hash = -join ($__siSupportSha.ComputeHash((New-Object System.Text.UTF8Encoding($false)).GetBytes($__body)) | ForEach-Object { $_.ToString('x2') })
        if ($__hash -ne $__siSupportFiles[$__k].Sha256) { throw "SecurityInsight standalone script: the embedded file '$__k' is damaged (SHA-256 mismatch) -- download the script again." }
        $__p = [IO.Path]::Combine($__siSupportDir, ($__k -replace '/', [string][IO.Path]::DirectorySeparatorChar))
        $__d = [IO.Path]::GetDirectoryName($__p)
        if (-not [IO.Directory]::Exists($__d)) { [void][IO.Directory]::CreateDirectory($__d) }
        [IO.File]::WriteAllText($__p, $__body, (New-Object System.Text.UTF8Encoding($__k -match '\.ps[dm]?1$')))
        $__siSupportWritten.Add($__p)
    }
    $__target = [IO.Path]::Combine($__siSupportDir, ($__siSupportEntry -replace '/', [string][IO.Path]::DirectorySeparatorChar))
    if ($env:SI_SUPPORT_SELFTEST -eq '1') {
        # the support pipeline's own check: every file extracted and verified, the entry script's parameters readable
        $__cmd = Get-Command -Name $__target -ErrorAction Stop
        [pscustomobject]@{ SISupportSelfTest = 'ok'; Version = $__siSupportVersion; Entry = $__siSupportEntry; Files = $__siSupportWritten.Count; Parameters = @($__cmd.Parameters.Keys) }
        return
    }
    $global:LASTEXITCODE = 0
    & $__target @PSBoundParameters
    $__exit = $LASTEXITCODE
} finally {
    $__siSupportSha.Dispose()
    foreach ($__p in $__siSupportWritten) { try { [IO.File]::Delete($__p) } catch { } }
    if ([IO.Directory]::Exists($__siSupportDir)) {
        $__left = @([IO.Directory]::GetFiles($__siSupportDir, '*', [IO.SearchOption]::AllDirectories))
        if ($__left.Count) { Write-Host ("SecurityInsight: the script left {0} file(s) (logs or output) in {1}" -f $__left.Count, $__siSupportDir) }
        else { try { [IO.Directory]::Delete($__siSupportDir, $true) } catch { } }
    }
}
if ($__exit) { exit $__exit }