<#
.SYNOPSIS
    Is this SecurityInsight install healthy, and is it isolated? Read-only.

.DESCRIPTION
    Reads the install's config (config/SecurityInsight.custom.ps1, without running it) and reports:
      1. rows and the last time per SI table in the install's workspace (Log Analytics data plane)
      2. run health per engine: the latest start and end, and how the last run ended (ExitReason)
      3. the data collection rules in its resource group
      4. ISOLATION -- the install's managed identity holds NO write role (Owner / Contributor / Monitoring Metrics
         Publisher / User Access Administrator / ...) outside its own resource group, except the grants SecurityInsight
         documents for it; and its data collection rule names are unique in the subscription (an engine that resolves a
         rule by name could otherwise send this install's data into another one)
      5. the licence request (when the config names its Key Vault): none / requested / pending / approved / rejected,
         valid-to and the last check, from the state the updater keeps (SI-LicenceRequest-State; never the pull token).
      6. updates (Pro, when the config names its Key Vault): the update source, the last manifest per kind (version,
         sequence, ring), the last check and any HOLD, from the state the updater keeps (SI-Update-State; never the
         install key). A refused manifest or an install key that could not be claimed is a finding; a hold is a note.
         A REJECTED request is wrong; a request's last problem is a note
      6. a summary. Exit code 1 when anything is wrong, 0 otherwise.

    Needs no PowerShell module: Azure is reached over plain REST. Signs in as the install's own identity from its config
    (its managed identity, or its service principal certificate from the machine's certificate store), or as the
    service principal certificate named in SI_DIAGNOSTICS_APPID / SI_DIAGNOSTICS_TENANTID / SI_DIAGNOSTICS_CERTTHUMBPRINT
    (-SignIn). The identity needs Reader on the install's resource group and subscription, and Log Analytics Reader on the workspace.

.PARAMETER ConfigPath
    The install's config file. Default: config/SecurityInsight.custom.ps1 of this copy.
.PARAMETER SinceHours
    How far back to look for data and runs (default 26: one daily run plus margin).
.PARAMETER RunningGraceHours
    A run that started longer ago than this and never ended is reported (default 4).
.PARAMETER IdentityName
    The install's user-assigned identity, when the config does not name it and its resource group holds more than one.
.PARAMETER PrincipalId
    The identity's object (principal) id -- any identity, also a VM's system-assigned one.
.PARAMETER AllowedGrant
    Extra write grants that are allowed on purpose, as 'Role@/scope'.
.PARAMETER SignIn
    Auto (default: the SI_DIAGNOSTICS_* service principal when set, otherwise Config) | Config (the install's own
    identity). AzContext is no longer supported: SecurityInsight v3 uses no Az PowerShell session.

.EXAMPLE
    ./diagnostics/Test-SIInstall.ps1
.EXAMPLE
    ./diagnostics/Test-SIInstall.ps1 -ConfigPath ./config/SecurityInsight.custom.ps1 -SinceHours 48 -PassThru

.LINK
    https://invardia.com/docs/si/scripts/Test-SIInstall/

.NOTES
    Requirements:
      PowerShell 7 (pwsh). Windows PowerShell 5.1 is refused at once (#Requires -Version 7.0).
      Role: Reader (and Log Analytics Reader on the workspace) -- 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,
    [double]$SinceHours = 26,
    [double]$RunningGraceHours = 4,
    [string]$IdentityName,
    [string]$PrincipalId,
    [string[]]$AllowedGrant = @(),
    [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 -- Test-SIInstall.ps1, standalone (Community edition). Built 2026-11-09T20:28:39Z from commit c1472e2f4c240c971c9559f07eef7e794b322001, source SOLUTIONS/SecurityInsight/diagnostics/Test-SIInstall.ps1,
# by release/Build-SISupportScripts.ps1 (framework SUPPORT-DL-1). Download: Invoke-WebRequest https://invardia.com/support/si/Test-SIInstall.ps1 -OutFile Test-SIInstall.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/Test-SIInstall.ps1'
$__siSupportFiles = [ordered]@{}
$__siSupportFiles['diagnostics/Test-SIInstall.ps1'] = @{ Sha256 = '7462f34ec43dae83fff85dcf579206f12257b712456c89f73485d6e267e2b7c5'; Text = @'
|<#
|.SYNOPSIS
|    Is this SecurityInsight install healthy, and is it isolated? Read-only.
|
|.DESCRIPTION
|    Reads the install's config (config/SecurityInsight.custom.ps1, without running it) and reports:
|      1. rows and the last time per SI table in the install's workspace (Log Analytics data plane)
|      2. run health per engine: the latest start and end, and how the last run ended (ExitReason)
|      3. the data collection rules in its resource group
|      4. ISOLATION -- the install's managed identity holds NO write role (Owner / Contributor / Monitoring Metrics
|         Publisher / User Access Administrator / ...) outside its own resource group, except the grants SecurityInsight
|         documents for it; and its data collection rule names are unique in the subscription (an engine that resolves a
|         rule by name could otherwise send this install's data into another one)
|      5. the licence request (when the config names its Key Vault): none / requested / pending / approved / rejected,
|         valid-to and the last check, from the state the updater keeps (SI-LicenceRequest-State; never the pull token).
|      6. updates (Pro, when the config names its Key Vault): the update source, the last manifest per kind (version,
|         sequence, ring), the last check and any HOLD, from the state the updater keeps (SI-Update-State; never the
|         install key). A refused manifest or an install key that could not be claimed is a finding; a hold is a note.
|         A REJECTED request is wrong; a request's last problem is a note
|      6. a summary. Exit code 1 when anything is wrong, 0 otherwise.
|
|    Needs no PowerShell module: Azure is reached over plain REST. Signs in as the install's own identity from its config
|    (its managed identity, or its service principal certificate from the machine's certificate store), or as the
|    service principal certificate named in SI_DIAGNOSTICS_APPID / SI_DIAGNOSTICS_TENANTID / SI_DIAGNOSTICS_CERTTHUMBPRINT
|    (-SignIn). The identity needs Reader on the install's resource group and subscription, and Log Analytics Reader on the workspace.
|
|.PARAMETER ConfigPath
|    The install's config file. Default: config/SecurityInsight.custom.ps1 of this copy.
|.PARAMETER SinceHours
|    How far back to look for data and runs (default 26: one daily run plus margin).
|.PARAMETER RunningGraceHours
|    A run that started longer ago than this and never ended is reported (default 4).
|.PARAMETER IdentityName
|    The install's user-assigned identity, when the config does not name it and its resource group holds more than one.
|.PARAMETER PrincipalId
|    The identity's object (principal) id -- any identity, also a VM's system-assigned one.
|.PARAMETER AllowedGrant
|    Extra write grants that are allowed on purpose, as 'Role@/scope'.
|.PARAMETER SignIn
|    Auto (default: the SI_DIAGNOSTICS_* service principal when set, otherwise Config) | Config (the install's own
|    identity). AzContext is no longer supported: SecurityInsight v3 uses no Az PowerShell session.
|
|.EXAMPLE
|    ./diagnostics/Test-SIInstall.ps1
|.EXAMPLE
|    ./diagnostics/Test-SIInstall.ps1 -ConfigPath ./config/SecurityInsight.custom.ps1 -SinceHours 48 -PassThru
|
|.LINK
|    https://invardia.com/docs/si/scripts/Test-SIInstall/
|#>
|[CmdletBinding(SupportsShouldProcess)]
|param(
|    [string]$ConfigPath,
|    [double]$SinceHours = 26,
|    [double]$RunningGraceHours = 4,
|    [string]$IdentityName,
|    [string]$PrincipalId,
|    [string[]]$AllowedGrant = @(),
|    [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 'Test-SIInstall' -Quiet:([bool]$PSBoundParameters.ContainsKey('Seams'))
|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 = Read-SIInstallConfigValues -Path $ConfigPath
|$target = Get-SIInstallTargetFromConfig -Values $values
|if (-not $Seams) { $null = Initialize-SIDiagnosticsSignIn -SignIn $SignIn -Values $values }
|$s = Merge-SIDiagnosticsSeams -Seams $Seams
|$r = Invoke-SIInstallCheck -Target $target -Seams $s -SinceHours $SinceHours -RunningGraceHours $RunningGraceHours `
|        -IdentityName $IdentityName -PrincipalId $PrincipalId -AllowedGrant $AllowedGrant
|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 }