Auditing Enterprise App Permissions

#Requires -Version 7.0
#Requires -Modules Microsoft.Graph.Authentication, Microsoft.Graph.Applications

<#
.SYNOPSIS
    Audits ContraForce enterprise application permissions in the current Microsoft Entra ID tenant.

.DESCRIPTION
    Queries Microsoft Graph for all documented ContraForce enterprise applications,
    resolves their delegated and application permissions to human-readable names,
    and outputs a structured JSON file suitable for diffing against documentation.

    Supports Commercial, GCC High, and DoD cloud environments.

    Requires:
    - Microsoft.Graph PowerShell modules:
        Install-Module Microsoft.Graph.Applications -Scope CurrentUser
    - An authenticated Microsoft Graph session with Directory.Read.All:
        Connect-MgGraph -Scopes "Application.Read.All","Directory.Read.All"
        Connect-MgGraph -Scopes "Application.Read.All","Directory.Read.All" -Environment USGov
    - The target tenant must have the ContraForce enterprise applications consented

.PARAMETER OutputPath
    Path for the output JSON file. Defaults to enterprise-apps-audit.json in the current directory.

.PARAMETER Cloud
    The Microsoft cloud environment to audit. Uses the same values as
    'az cloud set --name': AzureCloud (Commercial) or AzureUSGovernment
    (GCC High / DoD). Defaults to AzureCloud.

.PARAMETER AppsFile
    Path to a JSON file listing the applications to audit. Each entry must have
    'Name' and 'AppId' fields. Required for government cloud environments where
    app IDs differ from commercial. Contact [email protected] for your
    environment's app IDs.

.PARAMETER RedactUPN
    When set, records the operator's Entra object ID instead of the User Principal Name
    in the generatedBy metadata field. Automatically enabled for AzureUSGovernment
    to avoid recording PII in audit artifacts.

.EXAMPLE
    pwsh -File Audit-EnterpriseApps.ps1
    pwsh -File Audit-EnterpriseApps.ps1 -OutputPath ./audit-2026-02-12.json
    pwsh -File Audit-EnterpriseApps.ps1 -Cloud AzureUSGovernment -AppsFile ./gov-apps.json -OutputPath ./audit-gov.json
#>

param(
    [string]$OutputPath = "enterprise-apps-audit.json",

    [ValidateSet("AzureCloud", "AzureUSGovernment")]
    [string]$Cloud = "AzureCloud",

    [string]$AppsFile,

    [switch]$RedactUPN
)

$ErrorActionPreference = "Stop"

# ── Cloud environment metadata ───────────────────────────────────────────────
$EnvironmentNames = @{
    "AzureCloud"        = "Commercial"
    "AzureUSGovernment" = "US Government (GCC High / DoD)"
}

# Maps our -Cloud parameter values to the Connect-MgGraph -Environment values
# that Microsoft Graph PowerShell SDK uses internally.  GCC High uses "USGov"
# and DoD uses "USGovDoD" — both map to our single "AzureUSGovernment" value.
$ValidMgEnvironments = @{
    "AzureCloud"        = @("Global")
    "AzureUSGovernment" = @("USGov", "USGovDoD")
}

# ── Pre-flight: verify Microsoft Graph authentication ─────────────────────────
$context = Get-MgContext
if (-not $context) {
    $suggestedEnv = $ValidMgEnvironments[$Cloud][0]
    $envFlag = if ($Cloud -ne "AzureCloud") {
        " -Environment $suggestedEnv"
    } else { "" }
    Write-Error ("No active Microsoft Graph session. Connect first:`n" +
        "  Connect-MgGraph -Scopes 'Application.Read.All','Directory.Read.All'$envFlag`n" +
        "  Connect-MgGraph -Scopes 'Application.Read.All','Directory.Read.All'$envFlag -UseDeviceCode")
    exit 1
}

# Validate the connected environment matches the requested one.
# Connect-MgGraph -Environment uses "Global", "USGov", "USGovDoD" internally,
# so we check against the valid set for the -Cloud value the operator chose.
if ($context.Environment -notin $ValidMgEnvironments[$Cloud]) {
    $validList = $ValidMgEnvironments[$Cloud] -join "' or '"
    Write-Error ("Environment mismatch: connected to '$($context.Environment)' " +
        "but -Cloud '$Cloud' expects '$validList'.`n" +
        "Disconnect and reconnect to the correct environment:`n" +
        "  Disconnect-MgGraph`n" +
        "  Connect-MgGraph -Scopes 'Application.Read.All','Directory.Read.All' -Environment $($ValidMgEnvironments[$Cloud][0])")
    exit 1
}

# Resolve operator identity via Graph API (avoids parsing access tokens)
$meResponse = Invoke-MgGraphRequest -Uri '/me?$select=id,userPrincipalName' -Method GET
$operatorOid = $meResponse.id
$operatorUpn = $meResponse.userPrincipalName

# Auto-enable UPN redaction for government environments
$effectiveRedact = $RedactUPN.IsPresent -or ($Cloud -ne "AzureCloud")
$generatedBy = if ($effectiveRedact) { $operatorOid } else { $operatorUpn }

$envDisplayName = $EnvironmentNames[$Cloud]
Write-Host "Environment: $envDisplayName ($Cloud)" -ForegroundColor Green
Write-Host "Authenticated as: $generatedBy (Tenant: $($context.TenantId))" -ForegroundColor Green

# ── ContraForce enterprise applications to audit ──────────────────────────────
# App IDs differ by cloud environment.  The commercial IDs are built-in;
# government cloud app IDs are provided by ContraForce upon request and
# passed via -AppsFile.
if ($AppsFile) {
    $AppsToAudit = Get-Content $AppsFile -Raw | ConvertFrom-Json
} elseif ($Cloud -eq "AzureCloud") {
    $AppsToAudit = @(
        @{ Name = "ContraForce API"; AppId = "24d97bc0-8f2b-45d5-8e0b-7fe286732ef2" }
        @{ Name = "ContraForce Portal"; AppId = "8b7cb435-9526-47ee-b79a-34433f0daad2" }
        @{ Name = "ContraForce for MDE"; AppId = "6efccc6a-f0d3-49e5-92d0-17d4afa9ba52" }
        @{ Name = "ContraForce Gamebooks for MDE"; AppId = "ad7b0e79-3c37-4408-bf8f-eb89522cc920" }
        @{ Name = "ContraForce Gamebooks for Identity"; AppId = "36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a" }
        @{ Name = "ContraForce Gamebooks for Email"; AppId = "44dbf6fe-45e3-48a3-bac3-f8d4cf1dba6d" }
        @{ Name = "ContraForce Sentinel Hunting"; AppId = "6bf1c74d-7ade-4671-a507-166936f89a1f" }
        @{ Name = "ContraForce User Management"; AppId = "460b65b7-3a5e-4a2c-98d0-e48fd35374a9" }
    )
} else {
    Write-Error ("Government cloud environments require -AppsFile.`n" +
        "App IDs differ by cloud environment. Contact [email protected]`n" +
        "to obtain the app IDs for your environment.")
    exit 1
}

# ── Well-known first-party resource APIs ──────────────────────────────────────
# Maps Entra object IDs → friendly names for the Microsoft APIs that ContraForce
# integrates with. Object IDs are tenant-local so we resolve them at runtime.
$ResourceAPIs = @(
    "Microsoft Graph"
    "Windows Azure Service Management API"
    "WindowsDefenderATP"
    "Microsoft Threat Protection"
    "Log Analytics API"
)

# ── Friendly display names for resource APIs ──────────────────────────────────
$FriendlyNames = @{
    "Windows Azure Service Management API" = "Azure Service Management"
}

# ── Permission lookup tables ─────────────────────────────────────────────────
$AppRoleLookup = @{}       # resourceSPId -> { roleId -> { name, description } }
$DescByNameLookup = @{}    # resourceSPId -> { scopeName -> description }
$ResourceNameById = @{}    # resourceSPId -> friendly name

function Register-ServicePrincipal {
    param(
        [Parameter(Mandatory)]$Sp,
        [string]$FriendlyName
    )
    $id = $Sp.Id
    $ResourceNameById[$id] = if ($FriendlyName) { $FriendlyName } else { $Sp.DisplayName }

    $roles = @{}
    foreach ($role in $Sp.AppRoles) {
        $roles[$role.Id] = @{ name = $role.Value; description = $role.Description }
    }
    $AppRoleLookup[$id] = $roles

    $descByName = @{}
    foreach ($scope in $Sp.Oauth2PermissionScopes) {
        $descByName[$scope.Value] = $scope.AdminConsentDescription
    }
    $DescByNameLookup[$id] = $descByName
}

# ── Resolve resource API service principals ───────────────────────────────────
Write-Host "Resolving resource API service principals..." -ForegroundColor Cyan

foreach ($apiName in $ResourceAPIs) {
    $sp = Get-MgServicePrincipal -Filter "displayName eq '$apiName'" `
        -Property Id, DisplayName, AppRoles, Oauth2PermissionScopes -Top 1
    if (-not $sp) {
        Write-Warning "Resource API not found in tenant: $apiName"
        continue
    }

    $friendly = if ($FriendlyNames.ContainsKey($sp.DisplayName)) {
        $FriendlyNames[$sp.DisplayName]
    } else { $sp.DisplayName }
    Register-ServicePrincipal -Sp $sp -FriendlyName $friendly

    Write-Host "  Resolved: $friendly ($($sp.Id)) — $($AppRoleLookup[$sp.Id].Count) app roles, $($DescByNameLookup[$sp.Id].Count) delegated scopes"
}

# ── Also index ContraForce apps themselves (they expose internal scopes) ──────
# Why startswith('ContraForce')?
# Some ContraForce apps delegate to each other via custom oauth2 scopes (e.g. the
# Portal app exposes scopes consumed by the API app). To resolve these internal
# cross-app scopes to human-readable names instead of raw GUIDs, we index ALL
# service principals whose display name starts with "ContraForce" — not just the
# 8 customer-facing apps listed in $AppsToAudit. Permissions that originate from
# these internal apps are tagged with "internal": true in the output so auditors
# can distinguish them from Microsoft first-party API permissions.
$AllCFServicePrincipals = Get-MgServicePrincipal `
    -Filter "startswith(displayName, 'ContraForce')" `
    -Property Id, DisplayName, AppRoles, Oauth2PermissionScopes -All
foreach ($cfSp in $AllCFServicePrincipals) {
    if (-not $ResourceNameById.ContainsKey($cfSp.Id)) {
        Register-ServicePrincipal -Sp $cfSp
    }
}

# ── Audit each application ───────────────────────────────────────────────────
$results = [System.Collections.Generic.List[object]]::new()

foreach ($app in $AppsToAudit) {
    Write-Host "`nAuditing: $($app.Name) ($($app.AppId))..." -ForegroundColor Cyan

    # Find the service principal in this tenant
    $sp = Get-MgServicePrincipal -Filter "appId eq '$($app.AppId)'" `
        -Property Id, DisplayName, AppId -Top 1
    if (-not $sp) {
        Write-Warning "  NOT FOUND in tenant — skipping"
        $results.Add([ordered]@{
                applicationName        = $app.Name
                appId                  = $app.AppId
                status                 = "NOT_FOUND"
                delegatedPermissions   = @()
                applicationPermissions = @()
            })
        continue
    }
    $spId = $sp.Id

    # ── Delegated permissions (oauth2PermissionGrants) ────────────────────────
    $grants = Get-MgServicePrincipalOauth2PermissionGrant -ServicePrincipalId $spId -All
    $delegated = [System.Collections.Generic.List[object]]::new()

    foreach ($grant in $grants) {
        $resourceId = $grant.ResourceId
        $resourceName = if ($ResourceNameById.ContainsKey($resourceId)) {
            $ResourceNameById[$resourceId]
        } else { $resourceId }
        $isInternal = $resourceName -like "ContraForce *"
        $scopeNames = ($grant.Scope -split ' ') | Where-Object { $_ -ne '' } | Sort-Object

        foreach ($scope in $scopeNames) {
            $desc = if ($DescByNameLookup.ContainsKey($resourceId) -and
                        $DescByNameLookup[$resourceId].ContainsKey($scope)) {
                $DescByNameLookup[$resourceId][$scope]
            } else { $null }

            $delegated.Add([ordered]@{
                    permission  = $scope
                    api         = $resourceName
                    type        = "Delegated"
                    description = $desc
                    internal    = $isInternal
                })
        }
    }

    # ── Application permissions (appRoleAssignments) ──────────────────────────
    $assignments = Get-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $spId -All
    $appPerms = [System.Collections.Generic.List[object]]::new()

    foreach ($assignment in $assignments) {
        $resourceName = $assignment.ResourceDisplayName
        $resourceId = $assignment.ResourceId
        $roleId = $assignment.AppRoleId

        # Resolve the role ID to a permission name and description
        $permName = $roleId
        $desc = $null
        if ($AppRoleLookup.ContainsKey($resourceId)) {
            $lookup = $AppRoleLookup[$resourceId]
            if ($lookup.ContainsKey($roleId)) {
                $permName = $lookup[$roleId].name
                $desc = $lookup[$roleId].description
            }
        }

        # Use friendly resource name if available
        $friendlyResource = if ($ResourceNameById.ContainsKey($resourceId)) {
            $ResourceNameById[$resourceId]
        } else { $resourceName }

        $appPerms.Add([ordered]@{
                permission  = $permName
                api         = $friendlyResource
                type        = "Application"
                description = $desc
            })
    }

    # Sort for stable output
    $sortedDelegated = $delegated | Sort-Object { $_.api }, { $_.permission }
    $sortedAppPerms = $appPerms  | Sort-Object { $_.api }, { $_.permission }

    $results.Add([ordered]@{
            applicationName        = $sp.DisplayName
            appId                  = $sp.AppId
            status                 = "OK"
            delegatedPermissions   = @($sortedDelegated)
            applicationPermissions = @($sortedAppPerms)
        })

    Write-Host "  Delegated: $($delegated.Count) | Application: $($appPerms.Count)"
}

# ── Build output document ────────────────────────────────────────────────────
$output = [ordered]@{
    metadata     = [ordered]@{
        generatedAt  = (Get-Date -Format "o")
        tenantId     = $context.TenantId
        environment  = $Cloud
        generatedBy  = $generatedBy
        toolVersion  = "2.1.0"
        description  = "ContraForce enterprise application permissions snapshot for documentation auditing."
    }
    applications = @($results)
}

$fullPath = [System.IO.Path]::GetFullPath($OutputPath)
$json = $output | ConvertTo-Json -Depth 10
# Normalize to LF line endings
$json = $json -replace "`r`n", "`n"
[System.IO.File]::WriteAllText(
    $fullPath,
    "$json`n",
    [System.Text.UTF8Encoding]::new($false)
)

# ── Restrict file permissions for government environments ─────────────────────
# In GCC High and DoD environments, restrict the output file so only the current
# user can read/write it. This prevents other accounts on shared jump boxes from
# accessing tenant permission data.
if ($Cloud -ne "AzureCloud") {
    try {
        $acl = Get-Acl -Path $fullPath
        $acl.SetAccessRuleProtection($true, $false)  # disable inheritance, remove inherited rules
        $currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
        $rule = [System.Security.AccessControl.FileSystemAccessRule]::new(
            $currentUser,
            [System.Security.AccessControl.FileSystemRights]::FullControl,
            [System.Security.AccessControl.AccessControlType]::Allow
        )
        $acl.SetAccessRule($rule)
        Set-Acl -Path $fullPath -AclObject $acl
        Write-Host "  File permissions restricted to current user." -ForegroundColor Yellow
    } catch {
        Write-Warning "Could not restrict file permissions on '$fullPath': $_"
    }
}

Write-Host "`nAudit complete. Output written to: $OutputPath" -ForegroundColor Green
Write-Host "Environment: $envDisplayName"
Write-Host "Applications audited: $($results.Count)"
Write-Host "Tenant: $($context.TenantId)"

# ── Exit with non-zero code if any apps were not found ────────────────────────
$failures = @($results | Where-Object { $_.status -eq "NOT_FOUND" })
if ($failures.Count -gt 0) {
    Write-Warning "$($failures.Count) application(s) were not found in the tenant."
    exit 1
}