Public/New-PostureProfile.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.
function New-PostureProfile {
    <#
    .SYNOPSIS
        Writes profile.json, the org profile every check reads (spec 10.2): licenses, platforms, identity model,
        stance on BYOD, guests and Copilot, third-party controls, frameworks, thresholds, audience, cadence and
        break-glass accounts.
    .DESCRIPTION
        Interactive by default: about twelve questions, each with a default, the current value when the file
        already exists. Every answer is also a parameter, and -NonInteractive writes the profile from parameters and
        defaults without asking. Licenses are detected rather than typed: from 01-subscribed-skus.json in an
        evidence folder (-Evidence) or live from Graph (-FromGraph, read-only), then shown for confirmation.
    .PARAMETER Path
        Where to write. Default: ./profile.json. An existing file is read first and its answers become the defaults.
    .PARAMETER Evidence
        Evidence folder from Invoke-PostureCollection. Discovery reads it for the licenses, platforms, identity model,
        BYOD stance, external collaboration, Copilot status, tenant id and display name, and the wizard then asks only
        what evidence cannot answer: third-party controls, thresholds, break-glass accounts, frameworks, audience,
        cadence. Each discovered value is printed with the file and rule it came from; a parameter still wins.
    .PARAMETER AskAll
        Ask the discovered questions too, with the discovered values as defaults.
    .PARAMETER FromGraph
        Detect licenses from the signed-in Graph session (Organization.Read.All or Directory.Read.All).
    .PARAMETER NonInteractive
        Ask nothing; write parameters over existing values over defaults.
    .PARAMETER TenantId
        The tenant this profile belongs to. Invoke-PostureCollection -ProfilePath refuses a session in any other tenant; -FromGraph records the signed-in one.
    .PARAMETER BreakGlassTestedUtc
        When the break-glass accounts were last signed in and verified (operations answer; OP-003).
    .PARAMETER MessageCenterOwner
        Who reads the Microsoft 365 Message Center and turns changes into tickets (operations answer; OP-004).
    .PARAMETER SharePointClientId
        Application (client) id of the Entra app the SharePoint and Teams collector signs in with; deploy/setup/New-PostureSharePointApp.ps1 writes it.
    .PARAMETER Force
        Overwrite without asking, in interactive mode, when the file exists.
    .PARAMETER PassThru
        Return the profile object instead of the path.
    .EXAMPLE
        Connect-MgGraph -Scopes Organization.Read.All -NoWelcome
        New-PostureProfile -Path ~/tenantkeep/clients/contoso/profile.json -FromGraph

        Detects licenses, then asks the questions.
    .EXAMPLE
        New-PostureProfile -Path ./profile.json -NonInteractive -Licenses P1, Intune -Platforms windows, macOS -IdentityModel cloud-only -BreakGlass bg01@contoso.example, bg02@contoso.example -Thresholds @{ namePattern = '^CA\d{3} - ' }

        Scripted, no prompts.
    .OUTPUTS
        System.String, the file path. With -PassThru, the profile object.
    .LINK
        docs/profile.md
    #>

    [CmdletBinding(SupportsShouldProcess)]
    [OutputType([string], [System.Collections.Specialized.OrderedDictionary])]
    param(
        [string] $Path = './profile.json',
        [string] $Evidence,
        [switch] $FromGraph,
        [switch] $NonInteractive,
        [switch] $AskAll,
        [ValidateSet('E3', 'E5', 'BusinessPremium', 'P1', 'P2', 'Intune', 'IntuneSuite', 'EntraSuite', 'MDO1', 'MDO2', 'MDE1', 'MDE2', 'MDEBusiness', 'Purview', 'Copilot', 'SAM')]
        [string[]] $Licenses,
        [ValidateSet('windows', 'macOS', 'linux', 'iOS', 'android')] [string[]] $Platforms,
        [ValidateSet('cloud-only', 'hybrid-connect', 'hybrid-cloud-sync', 'hybrid-adfs')] [string] $IdentityModel,
        [ValidateSet('none', 'mam', 'mdm')] [string] $Byod,
        [ValidateSet('locked', 'governed', 'open')] [string] $ExternalCollaboration,
        [ValidateSet('none', 'pilot', 'deployed')] [string] $Copilot,
        [ValidateSet('none', 'platform', 'workloads')] [string] $Azure,
        [hashtable] $ThirdParty,
        [ValidateSet('none', 'hipaa', 'pci', 'cmmc', 'soc2', 'iso27001', 'nist-800-171', 'cisa-scuba')] [string[]] $Frameworks,
        [hashtable] $Thresholds,
        [string[]] $BreakGlass,
        [ValidateSet('executive', 'technical', 'auditor')] [string] $Audience,
        [ValidateSet('one-off', 'monthly', 'quarterly')] [string] $Cadence,
        [string] $ClientName,
        [ValidatePattern('^[0-9a-fA-F-]{36}$')] [string] $TenantId,
        [datetime] $BreakGlassTestedUtc,
        [string] $MessageCenterOwner,
        [ValidatePattern('^[0-9a-fA-F-]{36}$')] [string] $SharePointClientId,
        [switch] $Force,
        [switch] $PassThru
    )

    $ErrorActionPreference = 'Stop'
    Set-StrictMode -Version Latest

    $defaults = [ordered]@{
        clientName            = $null
        tenantId              = $null
        licenses              = @()
        platforms             = @('windows')
        identityModel         = 'cloud-only'
        byod                  = 'mam'
        externalCollaboration = 'governed'
        copilot               = 'none'
        azure                 = 'none'
        thirdParty            = [ordered]@{ email = 'none'; edr = 'none'; mfa = 'none'; mdm = 'none'; siem = 'none'; backup = 'none' }
        frameworks            = @()
        thresholds            = [ordered]@{ maxPermanentGlobalAdmins = 2; staleDeviceDays = 90; maxExclusionGroupMembers = 25; inactiveGuestDays = 90; reportOnlyMaxDays = 90; disabledMaxDays = 90; criticalCveMaxAgeDays = 14; namePattern = $null }
        audience              = 'technical'
        cadence               = 'quarterly'
        breakGlass            = @()
        operations            = [ordered]@{ breakGlassTestedUtc = $null; messageCenterOwner = $null }
        sharePointClientId    = $null
    }

    # Existing file: its answers become the defaults.
    $existing = $null
    if (Test-Path -LiteralPath $Path -PathType Leaf) {
        $existing = Get-Content -Raw -LiteralPath $Path | ConvertFrom-Json -AsHashtable -Depth 10
        foreach ($k in @($defaults.Keys)) {
            if (-not $existing.Contains($k)) { continue }
            if ($defaults[$k] -is [System.Collections.IDictionary]) { foreach ($sub in @($existing[$k].Keys)) { $defaults[$k][$sub] = $existing[$k][$sub] } }
            elseif ($defaults[$k] -is [array]) { $defaults[$k] = @($existing[$k]) }
            else { $defaults[$k] = $existing[$k] }
        }
    }

    # Parameters win over the file.
    if ($PSBoundParameters.ContainsKey('ClientName')) { $defaults.clientName = $ClientName }
    if ($TenantId) { $defaults.tenantId = $TenantId }
    if ($PSBoundParameters.ContainsKey('Licenses')) { $defaults.licenses = @($Licenses) }
    if ($PSBoundParameters.ContainsKey('Platforms')) { $defaults.platforms = @($Platforms) }
    if ($IdentityModel) { $defaults.identityModel = $IdentityModel }
    if ($Byod) { $defaults.byod = $Byod }
    if ($ExternalCollaboration) { $defaults.externalCollaboration = $ExternalCollaboration }
    if ($Copilot) { $defaults.copilot = $Copilot }
    if ($Azure) { $defaults.azure = $Azure }
    if ($ThirdParty) { foreach ($k in $ThirdParty.Keys) { $defaults.thirdParty[[string]$k] = [string]$ThirdParty[$k] } }
    if ($PSBoundParameters.ContainsKey('Frameworks')) { $defaults.frameworks = @($Frameworks | Where-Object { $_ -ne 'none' }) }
    if ($Thresholds) { foreach ($k in $Thresholds.Keys) { $defaults.thresholds[[string]$k] = $Thresholds[$k] } }
    if ($PSBoundParameters.ContainsKey('BreakGlass')) { $defaults.breakGlass = @($BreakGlass) }
    if ($PSBoundParameters.ContainsKey('BreakGlassTestedUtc')) { $defaults.operations.breakGlassTestedUtc = $BreakGlassTestedUtc.ToUniversalTime().ToString('o') }
    if ($PSBoundParameters.ContainsKey('MessageCenterOwner')) { $defaults.operations.messageCenterOwner = $MessageCenterOwner }
    if ($SharePointClientId) { $defaults.sharePointClientId = $SharePointClientId }
    if ($Audience) { $defaults.audience = $Audience }
    if ($Cadence) { $defaults.cadence = $Cadence }

    # Licenses: detected, then confirmed.
    $licenseSource = $(if ($existing -and $existing.Contains('licensesSource')) { $existing.licensesSource } else { 'manual' })
    $detected = $null
    $discovered = @()
    $discovery = $null
    if ($Evidence) {
        $discovery = Get-PostureProfileDiscovery -Evidence $Evidence
        $licenseSource = "evidence:$($discovery.evidence)"
        if ($discovery.facts.Contains('licenses')) { $detected = @($discovery.facts.licenses) }
        # Discovered values become the defaults unless the matching parameter was given.
        $paramFor = @{ platforms = 'Platforms'; identityModel = 'IdentityModel'; byod = 'Byod'; externalCollaboration = 'ExternalCollaboration'; copilot = 'Copilot'; tenantId = 'TenantId'; clientName = 'ClientName' }
        foreach ($k in @($discovery.facts.Keys | Where-Object { $_ -ne 'licenses' })) {
            if ($paramFor.ContainsKey($k) -and $PSBoundParameters.ContainsKey($paramFor[$k])) { continue }
            $defaults[$k] = $discovery.facts[$k]
            $discovered += $k
        }
        if ($null -ne $detected -and -not $PSBoundParameters.ContainsKey('Licenses')) { $discovered += 'licenses' }
        Write-PostureDiscovery -Discovery $discovery -Keys $discovered
    }
    elseif ($FromGraph) {
        $null = Assert-PostureGraphScope -AnyOfScope 'Organization.Read.All', 'Directory.Read.All'
        $detected = @(Get-PostureLicenseToken -Sku @(Invoke-PostureGraphRequest -Uri 'subscribedSkus' -ApiVersion 'v1.0'))
        $licenseSource = "graph:$((Get-Date).ToUniversalTime().ToString('yyyy-MM-dd'))"
        if (-not $TenantId) { $defaults.tenantId = [string](Get-MgContext).TenantId }
    }
    if ($null -ne $detected -and -not $PSBoundParameters.ContainsKey('Licenses')) { $defaults.licenses = $detected }

    $answers = $defaults
    if (-not $NonInteractive) {
        $ask = { param($q, $why, $choices, $default, [bool] $multi) Read-PostureAnswer -Question $q -Why $why -Choices $choices -Default $default -Multi:$multi }
        $skip = { param([string] $k) ($discovered -contains $k) -and -not $AskAll }
        if (-not (& $skip 'clientName')) { $answers.clientName = & $ask 'Client or tenant display name?' 'Shown on the report cover.' @() $answers.clientName $false }
        $licenseWhy = if ($null -ne $detected) { "Detected from $licenseSource. Edit the list if it is wrong." } else { 'Tokens: E3, E5, BusinessPremium, P1, P2, Intune, IntuneSuite, EntraSuite, MDO1, MDO2, MDE1, MDE2, MDEBusiness, Purview, Copilot, SAM. Use -FromGraph or -Evidence to detect.' }
        if (-not (& $skip 'licenses')) { $answers.licenses = @(& $ask 'Licenses present?' $licenseWhy @('E3', 'E5', 'BusinessPremium', 'P1', 'P2', 'Intune', 'IntuneSuite', 'EntraSuite', 'MDO1', 'MDO2', 'MDE1', 'MDE2', 'MDEBusiness', 'Purview', 'Copilot', 'SAM') $answers.licenses $true) }
        if (-not (& $skip 'platforms')) { $answers.platforms = @(& $ask 'Platforms in scope?' 'Decides which device and endpoint checks appear.' @('windows', 'macOS', 'linux', 'iOS', 'android') $answers.platforms $true) }
        if (-not (& $skip 'identityModel')) { $answers.identityModel = & $ask 'Identity model?' 'Hybrid renders the AD domain; ADFS adds the federation checks.' @('cloud-only', 'hybrid-connect', 'hybrid-cloud-sync', 'hybrid-adfs') $answers.identityModel $false }
        if (-not (& $skip 'byod')) { $answers.byod = & $ask 'BYOD stance for phones?' 'none: corporate devices only. mam: app protection without enrollment. mdm: enrolled.' @('none', 'mam', 'mdm') $answers.byod $false }
        if (-not (& $skip 'externalCollaboration')) { $answers.externalCollaboration = & $ask 'External collaboration stance?' 'locked: any guest is a finding. governed: guests with reviews pass. open: by policy.' @('locked', 'governed', 'open') $answers.externalCollaboration $false }
        if (-not (& $skip 'copilot')) { $answers.copilot = & $ask 'Copilot status?' 'Decides whether the readiness domain renders and how oversharing is scored.' @('none', 'pilot', 'deployed') $answers.copilot $false }
        $answers.azure = & $ask 'Azure footprint?' 'none, platform only, or workloads. Decides whether the Azure domain renders.' @('none', 'platform', 'workloads') $answers.azure $false
        foreach ($cat in @($answers.thirdParty.Keys)) {
            $answers.thirdParty[$cat] = & $ask "Third-party $cat control? (vendor name, or none)" 'Checks it covers render as "Covered by <vendor>" instead of failing.' @() $answers.thirdParty[$cat] $false
        }
        $answers.frameworks = @(& $ask 'Regulated frameworks?' 'Adds the crosswalk appendix and severity lifts on mapped checks.' @('none', 'hipaa', 'pci', 'cmmc', 'soc2', 'iso27001', 'nist-800-171', 'cisa-scuba') $(if (@($answers.frameworks).Count -eq 0) { @('none') } else { $answers.frameworks }) $true | Where-Object { $_ -ne 'none' })
        foreach ($t in @($answers.thresholds.Keys)) {
            $v = & $ask "Threshold ${t}?" 'Product default shown; the appendix prints your override next to it.' @() $answers.thresholds[$t] $false
            $answers.thresholds[$t] = $(if ($t -eq 'namePattern') { $(if ($v) { [string]$v } else { $null }) } else { [int]$v })
        }
        $answers.breakGlass = @(& $ask 'Break-glass account UPNs?' 'Exclusion checks then know which accounts are supposed to be excluded.' @() $answers.breakGlass $true)
        $testedAnswer = & $ask 'When were the break-glass accounts last tested (date, or blank)?' 'Sign in with each, confirm the exclusions and the alert; OP-003 wants it within six months.' @() $answers.operations.breakGlassTestedUtc $false
        $parsed = [datetime]::MinValue
        $answers.operations.breakGlassTestedUtc = $(if ($testedAnswer -and [datetime]::TryParse([string]$testedAnswer, [ref]$parsed)) { $parsed.ToUniversalTime().ToString('o') } else { if ($testedAnswer) { Write-Warning "Not a date: $testedAnswer; left blank." }; $null })
        $answers.operations.messageCenterOwner = & $ask 'Message Center triage owner (person or team, or blank)?' 'OP-004: who turns Microsoft 365 changes and retirements into tickets.' @() $answers.operations.messageCenterOwner $false
        $answers.audience = & $ask 'Primary audience?' 'executive: the 12-page view. technical: everything. auditor: crosswalk first.' @('executive', 'technical', 'auditor') $answers.audience $false
        $answers.cadence = & $ask 'Report cadence?' 'Sets the trend window and the "what changed" scope.' @('one-off', 'monthly', 'quarterly') $answers.cadence $false
    }

    $written = [ordered]@{ version = 1 }
    foreach ($k in $answers.Keys) { $written[$k] = $answers[$k] }
    $written.licensesSource = $licenseSource
    if ($discovery) { $written.discovery = [ordered]@{ evidence = $discovery.evidence; timestampUtc = [datetime]::UtcNow.ToString('o'); keys = @($discovered | Sort-Object); sources = $discovery.sources } }
    $written.createdUtc = $(if ($existing -and $existing.Contains('createdUtc')) { $existing.createdUtc } else { [datetime]::UtcNow.ToString('o') })
    $written.updatedUtc = [datetime]::UtcNow.ToString('o')

    if ($existing -and -not $NonInteractive -and -not $Force) {
        $ok = Read-PostureAnswer -Question "Overwrite ${Path}?" -Choices @('yes', 'no') -Default 'yes'
        if ($ok -ne 'yes') { Write-Warning 'Not written.'; if ($PassThru) { return $written }; return $null }
    }
    $full = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path)   # expands ~ too
    if ($PSCmdlet.ShouldProcess($full, 'Write profile.json')) {
        $dir = Split-Path $full -Parent
        if ($dir -and -not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
        [System.IO.File]::WriteAllText($full, (ConvertTo-Json -InputObject $written -Depth 10), [System.Text.UTF8Encoding]::new($false))
    }
    if ($PassThru) { return $written }
    return $full
}