feat(sharepoint): add permissions report and library management

Adds a full SharePoint Permissions report with cached data collection, PDF export, and oversharing signal detection (tenant-wide grants, external grants, direct Full Control, detached libraries).

Key additions:
- Backend: SharePointPermissions cache type, batched site collection via activity triggers, REST API endpoints for listing/setting/removing library permissions, role definitions, site user access, and multi-queue status
- Frontend: Permissions Report page with charts and filters, Library Permissions dialog (add/change/remove/inheritance control), Check User Access dialog, multi-queue progress tracker, query refresh button, reusable PDF primitives
- Sharing report enhancements: sprawl signals (anonymous editable links, never-expiring links, folder shares, external recipients), top libraries/recipients charts, PDF export, queue progress tracking

Synced from CyberDrain/CIPP@a2156f3

Author: github-actions[bot]

Config/CIPPDBCacheTypes.json

@@ -304,6 +304,11 @@
     "friendlyName": "SharePoint & OneDrive Sharing Links",
     "description": "Sharing links and external grants on SharePoint and OneDrive files and folders"
   },
+  {
+    "type": "SharePointPermissions",
+    "friendlyName": "SharePoint Permissions",
+    "description": "Site and document library permission assignments, including libraries that no longer inherit and grants to tenant-wide claims such as Everyone except external users"
+  },
   {
     "type": "OfficeActivations",
     "friendlyName": "Office Activations",

Modules/CIPPActivityTriggers/Public/Entrypoints/Activity Triggers/SharePoint Permissions/Push-DBCacheSharePointPermissionsBatch.ps1

@@ -0,0 +1,258 @@
+function Push-DBCacheSharePointPermissionsBatch {
+    <#
+    .SYNOPSIS
+        Collects site and document library permissions for a batch of SharePoint sites.
+
+    .DESCRIPTION
+        Processes up to 20 site seeds per activity via the SharePoint REST API with certificate
+        authentication. Each site is wrapped in its own try/catch so a batch of N sites always
+        returns exactly N site results - Push-StoreSharePointPermissions relies on that to verify
+        completeness before it replaces the cache.
+
+        Per site: the root web role assignments, then the visible document libraries. Only
+        libraries that hold their own permissions (HasUniqueRoleAssignments) are read - a library
+        that still inherits has exactly the site's permissions, so storing them would fill the
+        cache with rows carrying no information. Cache size therefore tracks governance drift
+        rather than tenant size.
+
+        Two row types are emitted, discriminated by rowType:
+        - Site       one per scanned site, always exactly one whether collection succeeded or not.
+                     Carries collectionStatus, the library counts and the error when Skipped.
+        - Assignment one per scope, principal and permission level. A principal holding several
+                     levels on the same scope produces one row per level, because each is granted
+                     and removed separately.
+
+        A library with unique permissions but no assignments (possible after breaking inheritance
+        without copying) still emits one Assignment row with null principal fields, so it is not
+        silently missing from the library inventory.
+
+        broadClaim flags the tenant-wide claims SharePoint exposes as well-known login names -
+        Everyone, Everyone except external users, and All Users. These are the oversharing
+        footgun this scan exists to surface.
+
+        collectionStatus:
+        - Full     the root web and every library that needed reading were collected
+        - Skipped  SPO REST collection failed for the site; no assignment rows are emitted.
+                   Push-StoreSharePointPermissions may restore this site's rows from the prior
+                   cache (merge-on-Skip) before the tenant write.
+
+        Consumer notes:
+        - Grant paths are not effective access: security groups are stored as principals and are
+          not expanded to their members
+        - Libraries that inherit are absent by design; their permissions are the site's
+        - Folder and file level permissions are out of scope (that would cost a full tree walk)
+
+    .FUNCTIONALITY
+        Entrypoint
+    #>
+    [CmdletBinding()]
+    param($Item)
+
+    $TenantFilter = $Item.TenantFilter
+    $BatchNumber = $Item.BatchNumber
+    $SiteSeeds = @($Item.Sites)
+
+    # Returns $true when a SharePoint principal is a guest/external identity.
+    function Test-SPGuestPrincipal {
+        param($Principal)
+        [bool]$Principal.IsShareByEmailGuestUser -or [bool]$Principal.IsEmailAuthenticationGuestUser -or
+            ($Principal.LoginName -match '(?i)#ext#|urn%3aspo%3aguest')
+    }
+
+    function Get-SPPrincipalType {
+        param($Entity)
+        if ($Entity.LoginName -match '(?i)federateddirectoryclaimprovider') { return 'M365 Group' }
+        switch ($Entity.PrincipalType) {
+            1 { 'User' }
+            4 { 'Security Group' }
+            8 { 'SharePoint Group' }
+            default { 'Other' }
+        }
+    }
+
+    # SharePoint expresses tenant-wide audiences as well-known claim login names. -like is used
+    # rather than -match because these contain regex metacharacters ( | ! ).
+    function Get-SPBroadClaim {
+        param([string]$LoginName)
+        if ([string]::IsNullOrWhiteSpace($LoginName)) { return $null }
+        if ($LoginName -like 'c:0(.s|true*') { return 'Everyone' }
+        if ($LoginName -like '*spo-grid-all-users*') { return 'EveryoneExceptExternal' }
+        if ($LoginName -like 'c:0!.s|windows*') { return 'AllUsers' }
+        return $null
+    }
+
+    # Flattens one roleassignments response into Assignment rows for a scope.
+    function ConvertTo-AssignmentRow {
+        param($Assignments, $Site, [string]$Scope, $Library, [string]$CollectedAt)
+
+        $Rows = [System.Collections.Generic.List[object]]::new()
+        foreach ($Assignment in @($Assignments)) {
+            $Member = $Assignment.Member
+            if (-not $Member) { continue }
+            $BroadClaim = Get-SPBroadClaim -LoginName ([string]$Member.LoginName)
+            foreach ($Binding in @($Assignment.RoleDefinitionBindings)) {
+                $Rows.Add([PSCustomObject]@{
+                        rowType           = 'Assignment'
+                        id                = "$($Site.SiteId)_$($Library.Id ?? 'root')_$($Member.Id)_$($Binding.Id)"
+                        siteId            = $Site.SiteId
+                        siteName          = $Site.SiteName
+                        siteUrl           = $Site.SiteUrl
+                        scope             = $Scope
+                        libraryId         = $Library.Id
+                        libraryTitle      = $Library.Title
+                        libraryUrl        = $Library.Url
+                        principalId       = [string]$Member.Id
+                        title             = $Member.Title
+                        loginName         = $Member.LoginName
+                        email             = $Member.Email
+                        userPrincipalName = if ($Member.PrincipalType -eq 1 -and $Member.LoginName) { ($Member.LoginName -split '\|')[-1] } else { $null }
+                        principalType     = Get-SPPrincipalType -Entity $Member
+                        isGuest           = (Test-SPGuestPrincipal $Member)
+                        permissionLevel   = $Binding.Name
+                        roleDefinitionId  = [string]$Binding.Id
+                        isSystemManaged   = ($Binding.RoleTypeKind -eq 1)
+                        broadClaim        = $BroadClaim
+                        # Boolean companion to broadClaim: the three claim types share no common
+                        # substring, so a table filter needs a single field to match on.
+                        isTenantWide      = [bool]$BroadClaim
+                        collectedAt       = $CollectedAt
+                    })
+            }
+        }
+        return $Rows
+    }
+
+    function New-SiteRow {
+        param($SiteSeed, [string]$Status, [string]$ErrorMessage, [int]$LibrariesScanned, [int]$LibrariesUnique, [string]$CollectedAt)
+        [PSCustomObject]@{
+            rowType                        = 'Site'
+            id                             = "$($SiteSeed.id)_site"
+            siteId                         = $SiteSeed.id
+            siteName                       = $SiteSeed.displayName
+            siteUrl                        = $SiteSeed.webUrl
+            collectionStatus               = $Status
+            collectionError                = $ErrorMessage
+            librariesScanned               = $LibrariesScanned
+            librariesWithUniquePermissions = $LibrariesUnique
+            collectedAt                    = $CollectedAt
+        }
+    }
+
+    $SiteResults = [System.Collections.Generic.List[object]]::new()
+
+    try {
+        Write-Information "Processing SharePoint permissions batch $BatchNumber for tenant $TenantFilter with $($SiteSeeds.Count) sites"
+
+        $SharePointInfo = Get-SharePointAdminLink -Public $false -tenantFilter $TenantFilter
+        $Scope = "$($SharePointInfo.SharePointUrl)/.default"
+        $JsonAccept = @{ Accept = 'application/json;odata=nometadata' }
+
+        foreach ($SiteSeed in $SiteSeeds) {
+            $CollectedAt = (Get-Date).ToUniversalTime().ToString('o')
+            $Rows = [System.Collections.Generic.List[object]]::new()
+            try {
+                $BaseUri = "$($SiteSeed.webUrl.TrimEnd('/'))/_api"
+                $SiteContext = [PSCustomObject]@{
+                    SiteId   = $SiteSeed.id
+                    SiteName = $SiteSeed.displayName
+                    SiteUrl  = $SiteSeed.webUrl
+                }
+                $NoLibrary = [PSCustomObject]@{ Id = $null; Title = $null; Url = $null }
+
+                # 1) Root web assignments.
+                $WebAssignments = @(New-GraphGetRequest -uri "$BaseUri/web/roleassignments?`$expand=Member,RoleDefinitionBindings" -tenantid $TenantFilter -scope $Scope -extraHeaders $JsonAccept -UseCertificate -AsApp $true)
+                foreach ($Row in (ConvertTo-AssignmentRow -Assignments $WebAssignments -Site $SiteContext -Scope 'Site' -Library $NoLibrary -CollectedAt $CollectedAt)) {
+                    $Rows.Add($Row)
+                }
+
+                # 2) Document libraries. BaseTemplate 101 is a document library, 119 the Site Pages
+                #    library - the same pair Invoke-ListSiteLibraries surfaces through Graph.
+                $Lists = @(New-GraphGetRequest -uri "$BaseUri/web/lists?`$select=Id,Title,Hidden,BaseTemplate,HasUniqueRoleAssignments,RootFolder/ServerRelativeUrl&`$expand=RootFolder" -tenantid $TenantFilter -scope $Scope -extraHeaders $JsonAccept -UseCertificate -AsApp $true)
+                $Libraries = @($Lists | Where-Object { $_.Hidden -ne $true -and $_.BaseTemplate -in @(101, 119) })
+
+                $UniqueCount = 0
+                foreach ($Library in $Libraries) {
+                    # $select should project HasUniqueRoleAssignments across the collection. If it
+                    # comes back null the property was not projected, so fall back to reading it
+                    # per library - one extra call each, the scan stays proportional to libraries.
+                    $HasUnique = $Library.HasUniqueRoleAssignments
+                    if ($null -eq $HasUnique) {
+                        Write-Information "SharePoint permissions: HasUniqueRoleAssignments not projected on the lists collection for '$($SiteSeed.webUrl)', falling back to a per-library check"
+                        $ListInfo = New-GraphGetRequest -uri "$BaseUri/web/lists(guid'$($Library.Id)')?`$select=HasUniqueRoleAssignments" -tenantid $TenantFilter -scope $Scope -extraHeaders $JsonAccept -UseCertificate -AsApp $true
+                        $HasUnique = $ListInfo.HasUniqueRoleAssignments
+                    }
+                    if ($HasUnique -ne $true) { continue }
+
+                    $UniqueCount++
+                    $LibraryContext = [PSCustomObject]@{
+                        Id    = [string]$Library.Id
+                        Title = $Library.Title
+                        Url   = $Library.RootFolder.ServerRelativeUrl
+                    }
+                    $LibraryAssignments = @(New-GraphGetRequest -uri "$BaseUri/web/lists(guid'$($Library.Id)')/roleassignments?`$expand=Member,RoleDefinitionBindings" -tenantid $TenantFilter -scope $Scope -extraHeaders $JsonAccept -UseCertificate -AsApp $true)
+                    $LibraryRows = ConvertTo-AssignmentRow -Assignments $LibraryAssignments -Site $SiteContext -Scope 'Library' -Library $LibraryContext -CollectedAt $CollectedAt
+                    foreach ($Row in $LibraryRows) { $Rows.Add($Row) }
+
+                    # Unique permissions but nothing granted: keep the library visible in the
+                    # inventory rather than letting it vanish from the counts.
+                    if ($LibraryRows.Count -eq 0) {
+                        $Rows.Add([PSCustomObject]@{
+                                rowType           = 'Assignment'
+                                id                = "$($SiteSeed.id)_$($Library.Id)_empty"
+                                siteId            = $SiteSeed.id
+                                siteName          = $SiteSeed.displayName
+                                siteUrl           = $SiteSeed.webUrl
+                                scope             = 'Library'
+                                libraryId         = $LibraryContext.Id
+                                libraryTitle      = $LibraryContext.Title
+                                libraryUrl        = $LibraryContext.Url
+                                principalId       = $null
+                                title             = $null
+                                loginName         = $null
+                                email             = $null
+                                userPrincipalName = $null
+                                principalType     = $null
+                                isGuest           = $false
+                                permissionLevel   = $null
+                                roleDefinitionId  = $null
+                                isSystemManaged   = $false
+                                broadClaim        = $null
+                                isTenantWide      = $false
+                                collectedAt       = $CollectedAt
+                            })
+                    }
+                }
+
+                $SiteResults.Add([PSCustomObject]@{
+                        SiteId           = $SiteSeed.id
+                        CollectionStatus = 'Full'
+                        SiteRow          = (New-SiteRow -SiteSeed $SiteSeed -Status 'Full' -ErrorMessage $null -LibrariesScanned $Libraries.Count -LibrariesUnique $UniqueCount -CollectedAt $CollectedAt)
+                        Rows             = @($Rows)
+                    })
+
+            } catch {
+                Write-LogMessage -API 'CIPPDBCache' -tenant $TenantFilter -message "SharePoint permissions: collection failed for '$($SiteSeed.webUrl)': $($_.Exception.Message)" -sev Warning
+                $SiteResults.Add([PSCustomObject]@{
+                        SiteId           = $SiteSeed.id
+                        CollectionStatus = 'Skipped'
+                        SiteRow          = (New-SiteRow -SiteSeed $SiteSeed -Status 'Skipped' -ErrorMessage $_.Exception.Message -LibrariesScanned 0 -LibrariesUnique 0 -CollectedAt $CollectedAt)
+                        Rows             = @()
+                    })
+            }
+        }
+
+        if ($SiteResults.Count -ne $SiteSeeds.Count) {
+            throw "Batch $BatchNumber invariant violated: expected $($SiteSeeds.Count) site results, got $($SiteResults.Count)"
+        }
+
+        return [PSCustomObject]@{
+            BatchNumber = $BatchNumber
+            Sites       = @($SiteResults)
+        }
+
+    } catch {
+        $ErrorMsg = "Failed SharePoint permissions batch $BatchNumber for tenant $TenantFilter : $($_.Exception.Message)"
+        Write-LogMessage -API 'CIPPDBCache' -tenant $TenantFilter -message $ErrorMsg -sev Error -LogData (Get-CippException -Exception $_)
+        throw
+    }
+}

Modules/CIPPActivityTriggers/Public/Entrypoints/Activity Triggers/SharePoint Permissions/Push-StoreSharePointPermissions.ps1

@@ -0,0 +1,96 @@
+function Push-StoreSharePointPermissions {
+    <#
+    .SYNOPSIS
+        Post-execution function that aggregates per-batch SharePoint permission rows and writes the cache.
+
+    .DESCRIPTION
+        Collects the Sites arrays returned by every Push-DBCacheSharePointPermissionsBatch activity,
+        flattens their Site and Assignment rows into a single row set, and writes
+        SharePointPermissions once via Add-CIPPDbItem.
+
+        Completeness guard: if the number of site results does not match ExpectedSiteCount the
+        function throws without writing. The cache is written in replace mode, so writing a partial
+        set would silently discard every site the failed batches were responsible for.
+
+        Merge-on-Skip: when a site returns Skipped, its rows are restored from the existing cache
+        (matched on siteId) so a transient SPO failure does not erase permission data that was
+        collected successfully on an earlier run. A Skipped site with no prior rows keeps just its
+        Site row, which carries collectionStatus and the error - the report can then say the site
+        could not be scanned rather than implying it has no permissions.
+
+        Row types written (see Push-DBCacheSharePointPermissionsBatch for the full schema):
+        - rowType 'Site'        one per site, always present, carries collectionStatus and library counts
+        - rowType 'Assignment'  one per scope, principal and permission level
+
+    .FUNCTIONALITY
+        Entrypoint
+    #>
+    [CmdletBinding()]
+    param($Item)
+
+    $TenantFilter = $Item.Parameters.TenantFilter
+    $ExpectedSiteCount = [int]$Item.Parameters.ExpectedSiteCount
+
+    try {
+        $SiteResults = [System.Collections.Generic.List[object]]::new()
+        foreach ($BatchResult in @($Item.Results)) {
+            foreach ($SiteResult in @($BatchResult.Sites)) {
+                if ($SiteResult) { $SiteResults.Add($SiteResult) }
+            }
+        }
+
+        $ActualCount = $SiteResults.Count
+        if ($ActualCount -ne $ExpectedSiteCount) {
+            throw "SharePoint permissions completeness check failed for $TenantFilter : expected $ExpectedSiteCount site results, got $ActualCount"
+        }
+
+        # Restore rows for sites that could not be collected this run.
+        $SkippedResults = @($SiteResults | Where-Object { $_.CollectionStatus -eq 'Skipped' })
+        $MergedCount = 0
+        $PriorRowsBySiteId = @{}
+        if ($SkippedResults.Count -gt 0) {
+            foreach ($Existing in @(New-CIPPDbRequest -TenantFilter $TenantFilter -Type 'SharePointPermissions')) {
+                if ($Existing.rowType -ne 'Assignment') { continue }
+                $Key = [string]$Existing.siteId
+                if (-not $Key) { continue }
+                if (-not $PriorRowsBySiteId.ContainsKey($Key)) {
+                    $PriorRowsBySiteId[$Key] = [System.Collections.Generic.List[object]]::new()
+                }
+                $PriorRowsBySiteId[$Key].Add($Existing)
+            }
+        }
+
+        $AllRows = [System.Collections.Generic.List[object]]::new()
+        foreach ($SiteResult in $SiteResults) {
+            if ($SiteResult.SiteRow) { $AllRows.Add($SiteResult.SiteRow) }
+
+            if ($SiteResult.CollectionStatus -eq 'Skipped') {
+                $Key = [string]$SiteResult.SiteId
+                if ($Key -and $PriorRowsBySiteId.ContainsKey($Key)) {
+                    foreach ($Row in $PriorRowsBySiteId[$Key]) { $AllRows.Add($Row) }
+                    $MergedCount++
+                }
+                continue
+            }
+
+            foreach ($Row in @($SiteResult.Rows)) {
+                if ($Row) { $AllRows.Add($Row) }
+            }
+        }
+
+        if ($SkippedResults.Count -gt 0) {
+            $RemainingSkipped = $SkippedResults.Count - $MergedCount
+            Write-LogMessage -API 'CIPPDBCache' -tenant $TenantFilter -message "SharePoint permissions: $($SkippedResults.Count) of $ActualCount sites returned Skipped from collection; restored $MergedCount from prior cache; $RemainingSkipped have no permission rows" -sev Warning
+        }
+
+        Add-CIPPDbItem -TenantFilter $TenantFilter -Type 'SharePointPermissions' -Data @($AllRows) -AddCount
+
+        $AssignmentCount = @($AllRows | Where-Object { $_.rowType -eq 'Assignment' }).Count
+        Write-LogMessage -API 'CIPPDBCache' -tenant $TenantFilter -message "Cached $AssignmentCount SharePoint permission assignments across $ActualCount sites ($MergedCount merge-on-Skip) from $(@($Item.Results).Count) batches" -sev Info
+        return
+
+    } catch {
+        Write-LogMessage -API 'CIPPDBCache' -tenant $TenantFilter -message "Failed to store SharePoint permissions: $($_.Exception.Message)" -sev Error -LogData (Get-CippException -Exception $_)
+        throw
+    }
+}