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.
- 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
| Column | What it tells you |
|---|---|
| LabelStatus | Labelled / No label / Protected - no label (RMS template or Restrict Access) / Unsupported type |
| Encrypted | Whether the file is an encrypted (RMS-protected) package |
| LabelId / LabelName | Label GUID(s) and name(s) read from the file's metadata |
| LabelTenantId | The tenant (SiteId) that owns the label |
| ForeignLabel | Yes when the label belongs to a tenant other than yours (common after mergers or external collaboration) |
| LabelMethod | How the label was applied (for example Standard or Privileged) |
| RmsUrls | Rights Management service URLs found inside legacy/encrypted files |
| ExternalLinks | External, non-hyperlink relationships (linked templates, data connections, OLE links) |
| Error | Download or parse failures, and files skipped for size |
How it works
| Step | Detail |
|---|---|
| 1. Authenticate | Client-credentials token for Microsoft Graph, refreshed every 50 minutes, with exponential back-off. |
| 2. Resolve the target | Site → document library (drive) → folder path, all via Graph. |
| 3. Walk the tree | Breadth-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 inspect | Each supported file is downloaded to a temp folder, inspected, then deleted. |
| 5. Classify | OOXML 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. Resilience | 429/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
| Item | Requirement |
|---|---|
| App registration | Microsoft Graph application permission Sites.Selected, admin consented, with a client secret (or adapt for a certificate). |
| Site grant | Sites.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 scopes | Don'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. |
| PowerShell | Windows PowerShell 5.1 or PowerShell 7. |
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
| Caveat | Why it matters |
|---|---|
| Co-authoring metadata location | When 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 files | An 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 labels | Labelled PDFs store metadata in XMP; detection relies on the MSIP_Label_ text being present uncompressed. |
| Downloads, not just metadata | Every scanned file is downloaded. Plan for bandwidth and time on large libraries, and keep $maxScanMB sensible. |
| Temp files | Files are deleted after each scan, but the temp folder holds content while the scan runs. Run it on a managed device. |
| Secrets | Prefer a certificate or prompting for the secret; never commit a populated settings block to source control. |
References
- Understanding Resource Specific Consent for Microsoft Graph and SharePoint Online
- Create permission on a site (Microsoft Graph)
- Metadata changes for sensitivity labels (co-authoring)
- LabelInfo members (Office)
PowerShellMicrosoft GraphSharePoint OnlineMicrosoft PurviewSensitivity LabelsSites.SelectedInformation ProtectionAzure RMS
No comments:
Post a Comment