Wednesday, November 18, 2026

Scan a SharePoint Folder for Sensitivity Labels, Encryption and External Links with Microsoft Graph and PowerShell

Scan a SharePoint Folder for Sensitivity Labels, Encryption and External Links

Microsoft Graph + PowerShell · app-only · scoped to one site with Sites.Selected

Before a migration, a tenant-to-tenant move or a records clean-up, you often need to answer a simple question: which files in this library are labelled, which are encrypted, and which carry a label from another tenant? SharePoint's UI won't give you that across thousands of nested files. This post walks through a PowerShell script that does it with an app-only Microsoft Graph connection scoped to a single site.

TL;DR
  • Recursively walks a library folder via Graph and downloads each supported file to a temp folder.
  • Reads MSIP_Label_* metadata to find label ID, name, owning tenant and method.
  • Flags encrypted files, labels from foreign tenants and external links.
  • Exports everything to CSV, with retry/back-off and partial saves for long runs.

What the script reports

ColumnWhat it tells you
LabelStatusLabelled / No label / Protected - no label (RMS template or Restrict Access) / Unsupported type
EncryptedWhether the file is an encrypted (RMS-protected) package
LabelId / LabelNameLabel GUID(s) and name(s) read from the file's metadata
LabelTenantIdThe tenant (SiteId) that owns the label
ForeignLabelYes when the label belongs to a tenant other than yours (common after mergers or external collaboration)
LabelMethodHow the label was applied (for example Standard or Privileged)
RmsUrlsRights Management service URLs found inside legacy/encrypted files
ExternalLinksExternal, non-hyperlink relationships (linked templates, data connections, OLE links)
ErrorDownload or parse failures, and files skipped for size

How it works

StepDetail
1. AuthenticateClient-credentials token for Microsoft Graph, refreshed every 50 minutes, with exponential back-off.
2. Resolve the targetSite → document library (drive) → folder path, all via Graph.
3. Walk the treeBreadth-first queue over /children with $top=999 and @odata.nextLink paging. Folders that fail are logged to a separate CSV instead of stopping the run.
4. Download and inspectEach supported file is downloaded to a temp folder, inspected, then deleted.
5. ClassifyOOXML files (ZIP signature PK\x03\x04) are opened and docProps/custom.xml is parsed for MSIP_Label_<GUID>_* properties. Anything else (legacy binary formats, encrypted packages, PDF) is scanned as raw text for EncryptedPackage, DRMEncrypted, DataSpaces and RMS URLs.
6. Resilience429/503 responses honour Retry-After; 401/403/404 fail fast; a partial CSV is written every N files so a long run is never lost.

Prerequisites

ItemRequirement
App registrationMicrosoft Graph application permission Sites.Selected, admin consented, with a client secret (or adapt for a certificate).
Site grantSites.Selected grants nothing on its own. An admin must grant the app read on the target site via POST /sites/{siteId}/permissions or Grant-PnPEntraIDAppSitePermission.
Avoid broad scopesDon't also add Sites.Read.All or Files.Read.All to the same app, or the site-level restriction is no longer the effective limit.
PowerShellWindows PowerShell 5.1 or PowerShell 7.
Tip: Grant the app read only. The scanner never writes, so there's no reason to give it more.

Example grant (run with an identity that has Sites.FullControl.All):

POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions
Content-Type: application/json

{
  "roles": ["read"],
  "grantedToIdentities": [
    { "application": { "id": "<app-client-id>", "displayName": "Label Scanner" } }
  ]
}

The script

Fill in the settings block at the top. Leave $clientSecret empty to be prompted at run time so the secret never sits in the file. The script has no param() block, so you can also step through it line by line.

# ===== Settings =====
$tenantId     = "<your-tenant-id>"
$clientId     = "<your-app-client-id>"
$clientSecret = ""                     # leave empty to be prompted
$hostName     = "contoso.sharepoint.com"
$sitePath     = "/sites/ProjectSite"
$libraryName  = "Documents"
$folderPath   = "General/Project Files"
$outFolder    = "C:\Temp\LabelScan"
$outputCsv    = Join-Path $outFolder "Graph_LabelScan_$(Get-Date -Format 'yyyyMMdd_HHmmss').csv"
$tempRoot     = Join-Path $outFolder "Graph_LabelScan_tmp"
$homeTenantId = $tenantId
$maxScanMB    = 200
$saveEvery    = 100                    # write partial CSV every N files
$extensions   = @(".docx",".docm",".dotx",".xlsx",".xlsm",".xltx",".xlsb",".pptx",".pptm",".potx",".ppsx",".vsdx",".doc",".xls",".ppt",".pdf")
$graph        = "https://graph.microsoft.com/v1.0"

if (-not $clientSecret) { $clientSecret = Read-Host "Client secret" }

Add-Type -AssemblyName System.IO.Compression.FileSystem
$guidRx = '[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}'
New-Item -ItemType Directory -Path $outFolder -Force | Out-Null
New-Item -ItemType Directory -Path $tempRoot  -Force | Out-Null

# ================= Label parsing =================
function Get-LabelInfo($text) {
    $props = @{}
    $rx = "MSIP_Label_($guidRx)_(\w+)(?:`"[^>]*>\s*<vt:lpwstr>|>)([^<]*)"
    foreach ($m in [regex]::Matches($text, $rx)) {
        $id = $m.Groups[1].Value.ToLower()
        if (-not $props.ContainsKey($id)) { $props[$id] = @{} }
        $props[$id][$m.Groups[2].Value] = $m.Groups[3].Value
    }
    foreach ($m in [regex]::Matches($text, "MSIP_Label_($guidRx)_")) {
        $id = $m.Groups[1].Value.ToLower()
        if (-not $props.ContainsKey($id)) { $props[$id] = @{} }
    }
    return $props
}

function Get-FileScan($path) {
    $r = [ordered]@{ LabelStatus=""; Encrypted=""; LabelId=""; LabelName=""; LabelTenantId=""; ForeignLabel=""; LabelMethod=""; RmsUrls=""; ExternalLinks="" }

    $fs  = [System.IO.File]::Open($path, 'Open', 'Read', 'ReadWrite')
    $hdr = New-Object byte[] 4
    [void]$fs.Read($hdr, 0, 4)
    $fs.Close()
    $sig = ($hdr | ForEach-Object { $_.ToString("X2") }) -join ""
    $labels = @{}

    if ($sig -eq "504B0304") {
        $r.Encrypted = "No"
        $zip = [System.IO.Compression.ZipFile]::OpenRead($path)
        try {
            $custom = $zip.GetEntry("docProps/custom.xml")
            if ($custom) {
                $sr = New-Object System.IO.StreamReader($custom.Open())
                $labels = Get-LabelInfo $sr.ReadToEnd()
                $sr.Close()
            }
            $links = foreach ($e in $zip.Entries) {
                if ($e.FullName -like "*.rels") {
                    $sr = New-Object System.IO.StreamReader($e.Open())
                    $relXml = [xml]$sr.ReadToEnd()
                    $sr.Close()
                    $relXml.Relationships.Relationship |
                        Where-Object { $_.TargetMode -eq "External" -and $_.Type -notmatch "hyperlink" } |
                        ForEach-Object { $_.Target }
                }
            }
            $r.ExternalLinks = (@($links) | Sort-Object -Unique) -join "; "
        } finally {
            $zip.Dispose()
        }
    } else {
        $bytes = [System.IO.File]::ReadAllBytes($path)
        $text  = [System.Text.Encoding]::Unicode.GetString($bytes) + [System.Text.Encoding]::ASCII.GetString($bytes)
        if ($text -match "EncryptedPackage|DRMEncrypted|DataSpaces|MicrosoftIRMServices") { $r.Encrypted = "Yes" } else { $r.Encrypted = "No" }
        $labels = Get-LabelInfo $text
        $r.RmsUrls = ([regex]::Matches($text, 'https?://[A-Za-z0-9\.\-/_:]+') |
            ForEach-Object { $_.Value } |
            Where-Object { $_ -match "aadrm|azurerms|/_wmcs|rms\." } |
            Sort-Object -Unique) -join "; "
    }

    $active = @($labels.Keys | Where-Object { $labels[$_]["Enabled"] -ne "false" })
    if ($active.Count -gt 0) {
        $r.LabelStatus   = "Labelled"
        $r.LabelId       = $active -join "; "
        $r.LabelName     = ($active | ForEach-Object { $labels[$_]["Name"] }   | Where-Object { $_ }) -join "; "
        $r.LabelTenantId = ($active | ForEach-Object { $labels[$_]["SiteId"] } | Where-Object { $_ } | Sort-Object -Unique) -join "; "
        $r.LabelMethod   = ($active | ForEach-Object { $labels[$_]["Method"] } | Where-Object { $_ }) -join "; "
        if ($homeTenantId -and $r.LabelTenantId) {
            if ($r.LabelTenantId -notmatch [regex]::Escape($homeTenantId)) { $r.ForeignLabel = "Yes" } else { $r.ForeignLabel = "No" }
        }
    } elseif ($r.Encrypted -eq "Yes") {
        $r.LabelStatus = "Protected - no label (RMS template / Restrict Access)"
    } else {
        $r.LabelStatus = "No label"
    }
    return $r
}

# ================= Graph helpers =================
$tokenTime = [datetime]::MinValue
function Get-Headers {
    if (((Get-Date) - $script:tokenTime).TotalMinutes -gt 50) {
        $body = @{ client_id = $clientId; client_secret = $clientSecret; scope = "https://graph.microsoft.com/.default"; grant_type = "client_credentials" }
        for ($a = 1; $a -le 5; $a++) {
            try {
                $script:token = (Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -Body $body -ErrorAction Stop).access_token
                $script:tokenTime = Get-Date
                break
            } catch {
                if ($a -eq 5) { throw }
                Start-Sleep -Seconds ([math]::Pow(2, $a))
            }
        }
    }
    return @{ Authorization = "Bearer $script:token" }
}

function Get-RetryWait($err, $attempt) {
    $wait = [math]::Pow(2, $attempt)                          # 2,4,8,16,32 sec
    $status = $null
    if ($err.Exception.Response) { $status = [int]$err.Exception.Response.StatusCode }
    if ($status -eq 429 -or $status -eq 503) {
        $ra = $null
        try { $ra = $err.Exception.Response.Headers.RetryAfter.Delta.TotalSeconds } catch { }
        if ($ra) { $wait = [math]::Max($wait, $ra) }
    }
    return @{ Wait = $wait; Status = $status }
}

function Invoke-GraphGet($uri) {
    $attempt = 0
    while ($true) {
        $attempt++
        try {
            return Invoke-RestMethod -Uri $uri -Headers (Get-Headers) -ErrorAction Stop
        } catch {
            $info = Get-RetryWait $_ $attempt
            if ($attempt -ge 6 -or $info.Status -in 401,403,404) { throw }
            Write-Host "  Retry $attempt in $($info.Wait)s : $($_.Exception.Message)" -ForegroundColor DarkYellow
            Start-Sleep -Seconds $info.Wait
        }
    }
}

function Save-GraphFile($uri, $outFile) {
    $attempt = 0
    while ($true) {
        $attempt++
        try {
            Invoke-WebRequest -Uri $uri -Headers (Get-Headers) -OutFile $outFile -UseBasicParsing -ErrorAction Stop
            return
        } catch {
            $info = Get-RetryWait $_ $attempt
            if ($attempt -ge 6 -or $info.Status -in 401,403,404) { throw }
            Write-Host "  Download retry $attempt in $($info.Wait)s : $($_.Exception.Message)" -ForegroundColor DarkYellow
            Start-Sleep -Seconds $info.Wait
        }
    }
}

# ================= Site / library / folder =================
try {
    $site = Invoke-GraphGet "$graph/sites/${hostName}:${sitePath}"
} catch {
    Write-Host "Cannot access site - app is probably NOT granted via Sites.Selected. $($_.Exception.Message)" -ForegroundColor Red
    return
}
$drive = (Invoke-GraphGet "$graph/sites/$($site.id)/drives").value | Where-Object { $_.name -eq $libraryName }
if (-not $drive) { Write-Host "Library '$libraryName' not found." -ForegroundColor Red; return }

$encPath = ($folderPath.Split('/') | ForEach-Object { [Uri]::EscapeDataString($_) }) -join '/'
$root = Invoke-GraphGet "$graph/drives/$($drive.id)/root:/${encPath}"
Write-Host "Scanning: $($root.webUrl)" -ForegroundColor Cyan

# ================= Walk folder tree =================
$queue         = New-Object System.Collections.Queue
$files         = New-Object System.Collections.Generic.List[object]
$seen          = New-Object System.Collections.Generic.HashSet[string]
$failedFolders = New-Object System.Collections.Generic.List[object]
$queue.Enqueue($root.id)

while ($queue.Count -gt 0) {
    $folderId = $queue.Dequeue()
    $url = "$graph/drives/$($drive.id)/items/$folderId/children?`$top=999"
    while ($url) {
        $page = $null
        try {
            $page = Invoke-GraphGet $url
        } catch {
            $failedFolders.Add([pscustomobject]@{ FolderId = $folderId; Error = $_.Exception.Message })
            break
        }
        foreach ($c in $page.value) {
            if (-not $seen.Add($c.id)) { continue }
            if ($c.folder) { $queue.Enqueue($c.id) } else { $files.Add($c) }
        }
        $url = $page.'@odata.nextLink'
        Start-Sleep -Milliseconds 100
    }
    Write-Host "`rFolders left: $($queue.Count)  Files found: $($files.Count)   " -NoNewline
}
Write-Host ""
Write-Host "Files found    : $($files.Count)" -ForegroundColor Cyan
Write-Host "Failed folders : $($failedFolders.Count)" -ForegroundColor Yellow
if ($failedFolders.Count -gt 0) {
    $failedFolders | Format-Table -AutoSize
    $failedFolders | Export-Csv -LiteralPath ($outputCsv -replace '\.csv$', '_FailedFolders.csv') -NoTypeInformation -Encoding UTF8
}

# ================= Download + scan =================
$results = New-Object System.Collections.Generic.List[object]
$i = 0
foreach ($f in $files) {
    $i++
    $ext = [System.IO.Path]::GetExtension($f.name).ToLower()
    Write-Progress -Activity "Scanning" -Status "$i / $($files.Count) : $($f.name)" -PercentComplete (($i / [math]::Max($files.Count,1)) * 100)

    $row = [ordered]@{
        FolderPath    = [Uri]::UnescapeDataString(($f.parentReference.path -replace '^/drives/[^/]+/root:', ''))
        FileName      = $f.name
        FileUrl       = $f.webUrl
        Extension     = $ext
        SizeKB        = [math]::Round($f.size / 1KB, 1)
        Modified      = $f.lastModifiedDateTime
        LabelStatus   = ""
        Encrypted     = ""
        LabelId       = ""
        LabelName     = ""
        LabelTenantId = ""
        ForeignLabel  = ""
        LabelMethod   = ""
        RmsUrls       = ""
        ExternalLinks = ""
        Error         = ""
    }

    if ($extensions -notcontains $ext) {
        $row.LabelStatus = "Unsupported type"
    } elseif ($f.size -gt ($maxScanMB * 1MB)) {
        $row.Error = "Skipped download (> $maxScanMB MB)"
    } else {
        $tmpFile = Join-Path $tempRoot ("{0}{1}" -f $f.id, $ext)
        try {
            Save-GraphFile "$graph/drives/$($drive.id)/items/$($f.id)/content" $tmpFile
            $scan = Get-FileScan $tmpFile
            foreach ($k in $scan.Keys) { $row[$k] = $scan[$k] }
        } catch {
            $row.Error = $_.Exception.Message
        } finally {
            Remove-Item -LiteralPath $tmpFile -Force -ErrorAction SilentlyContinue
        }
    }
    $results.Add([pscustomobject]$row)

    if ($i % $saveEvery -eq 0) {
        $results | Export-Csv -LiteralPath $outputCsv -NoTypeInformation -Encoding UTF8
    }
}

Write-Progress -Activity "Scanning" -Completed
$results | Export-Csv -LiteralPath $outputCsv -NoTypeInformation -Encoding UTF8

# ================= Summary =================
$results | Group-Object LabelStatus | Select-Object Count, Name | Format-Table -AutoSize
Write-Host "Encrypted files : $(@($results | Where-Object Encrypted -eq 'Yes').Count)" -ForegroundColor Yellow
Write-Host "Foreign labels  : $(@($results | Where-Object ForeignLabel -eq 'Yes').Count)" -ForegroundColor Yellow
Write-Host "With ext. links : $(@($results | Where-Object { $_.ExternalLinks }).Count)" -ForegroundColor Yellow
Write-Host "Errors          : $(@($results | Where-Object { $_.Error }).Count)" -ForegroundColor Yellow
Write-Host "CSV saved to    : $outputCsv" -ForegroundColor Green

Sample console summary

Count Name
----- ----
  812 No label
  264 Labelled
   37 Protected - no label (RMS template / Restrict Access)
   55 Unsupported type

Encrypted files : 41
Foreign labels  : 9
With ext. links : 23
Errors          : 2

Illustrative numbers only.

Things to know before you trust the results

Heads-up: If your tenant has co-authoring for encrypted files turned on, newly labelled unencrypted Office files may show as "No label" here. See the first row below.
CaveatWhy it matters
Co-authoring metadata locationWhen co-authoring for encrypted files is enabled in Purview, Office stops writing label metadata to custom properties for newly labelled files and uses docMetadata/LabelInfo.xml instead. This script reads docProps/custom.xml, so in those tenants it can report recently labelled unencrypted files as "No label". Extend Get-FileScan to also read docMetadata/LabelInfo.xml if that setting is on.
Encrypted Office filesAn encrypted .docx/.xlsx/.pptx is stored as an OLE compound file, not a ZIP, so it goes through the raw-text branch. The label is usually still discoverable there, but name/method fields can be partial.
PDF labelsLabelled PDFs store metadata in XMP; detection relies on the MSIP_Label_ text being present uncompressed.
Downloads, not just metadataEvery scanned file is downloaded. Plan for bandwidth and time on large libraries, and keep $maxScanMB sensible.
Temp filesFiles are deleted after each scan, but the temp folder holds content while the scan runs. Run it on a managed device.
SecretsPrefer a certificate or prompting for the secret; never commit a populated settings block to source control.

References

PowerShellMicrosoft GraphSharePoint OnlineMicrosoft PurviewSensitivity LabelsSites.SelectedInformation ProtectionAzure RMS

No comments:

Post a Comment

Featured Post

Is This Office File RMS-Protected? Find Out with One PowerShell Script

Is This Office File RMS-Protected? Find Out with One PowerShell Script When a user says "I can't open this PowerPoint" or ...

Popular posts