#Requires -Version 5.1
<#
.SYNOPSIS
Filer Manager - analyse des dossiers Windows et rapporte les tailles des
dossiers, les chemins trop longs et les permissions NTFS, avec export HTML et CSV.
.DESCRIPTION
S'exécute avec une interface graphique WinForms par défaut. Peut aussi
s'exécuter sans interface (mode headless) pour la planification :
.\filer-manager.ps1 -Path "D:\Shares\Public" -Output report.html -NoGui
Fonctionne sur Windows PowerShell 5.1 et PowerShell 7+.
.PARAMETER Path
Un ou plusieurs dossiers racines à analyser. S'il est fourni avec -Output (ou
avec -NoGui), le script s'exécute sans interface et écrit un rapport HTML.
Accepte un chemin local, un chemin UNC (\\serveur\partage\dossier) ou un
lecteur réseau mappé (Z:\dossier). Un lecteur mappé est automatiquement
réécrit vers sa cible UNC lorsque la lettre n'est pas montée dans le jeton
courant : les mappages appartiennent à la session qui les a créés, donc ceux
de l'utilisateur interactif sont absents d'une exécution en mode élevé (et
inversement). En tâche planifiée sous un autre compte, indiquez l'UNC.
.PARAMETER Output
Chemin du rapport HTML à écrire en mode headless.
.PARAMETER CsvOutput
Chemin de base du/des rapport(s) CSV à écrire en mode headless. Un fichier CSV
distinct est produit par catégorie ayant des données (p. ex. base.csv ->
base-tree.csv, base-permissions.csv, ...). Peut être combiné avec -Output pour
écrire HTML et CSV en même temps, ou utilisé seul pour un export CSV uniquement.
.PARAMETER MaxPathLength
Longueur de chemin (caractères) à partir de laquelle un élément est signalé
comme « trop long ». Par défaut 260 (Windows MAX_PATH).
.PARAMETER PermissionDepth
Nombre de niveaux de dossiers sous chaque racine pour lesquels collecter les
permissions NTFS. 0 = racines uniquement, 1 = racines + enfants immédiats
(par défaut), etc.
.PARAMETER IncludeFilesInTree
Inclure les fichiers individuels (pas seulement les dossiers) dans
l'arborescence des tailles.
.PARAMETER ExcludeFolder
Noms de dossiers à exclure de l'analyse (tailles, chemins trop longs et
permissions). Les jokers sont acceptés et la comparaison est insensible à la
casse, p. ex. '#recycle', '@eaDir', 'Thumbs*'. Par défaut, les corbeilles et
dossiers système courants sont exclus : #recycle et @eaDir (NAS Synology) et
$RECYCLE.BIN (corbeille Windows). Passez une liste vide (-ExcludeFolder @())
pour ne rien exclure par nom.
.PARAMETER ExcludeHidden
Exclure de l'analyse les dossiers portant l'attribut « masqué ».
.PARAMETER HideInheritedChildPerms
Omettre des rapports les permissions héritées portées par les dossiers
enfants (les entrées héritées qui ne font que recopier celles du parent). Les
permissions héritées des dossiers racines sont conservées, car le parent d'une
racine est hors analyse et ces entrées sont la seule trace des droits en vigueur.
.PARAMETER HideSystemPrincipals
Omettre des rapports les permissions portées par des comptes/groupes système
et intégrés bien connus (p. ex. NT AUTHORITY\SYSTEM, BUILTIN\Administrators,
CREATOR OWNER, NT SERVICE\*). La détection se fait par SID (indépendante de la
langue), avec un repli sur le nom. Utile pour ne garder que les identités
métier dans l'audit des permissions.
.PARAMETER GrantAccess
Lorsqu'un dossier/fichier ne peut pas être lu (accès refusé), s'approprie
automatiquement la propriété pour Administrators et accorde le FullControl à
BUILTIN\Administrators, puis réessaye. Nécessite une exécution en mode élevé.
Chaque modification est consignée dans le rapport.
.PARAMETER KeepGrants
Conserver l'accès accordé par -GrantAccess après l'analyse. Par défaut, l'outil
annule chaque modification une fois l'analyse terminée (en restaurant le
propriétaire et l'ACL d'origine là où ils ont pu être lus au préalable).
.PARAMETER NoGui
Forcer le mode sans interface (nécessite -Path et -Output).
.PARAMETER RevertPendingGrants
Annuler les modifications d'accès laissées par une exécution précédente qui
s'est arrêtée avant de les restaurer (interface fermée pendant l'analyse,
plantage, fermeture de session). Chaque octroi est journalisé sous
%LOCALAPPDATA%\FilerManager avant d'être appliqué ; ce commutateur rejoue les
journaux orphelins puis se termine. Ne demande aucun autre paramètre.
.PARAMETER Category
Catégories de rapport à inclure dans le HTML. Par défaut 'All'. Passez toute
combinaison de : Tree (tailles des dossiers), LongPaths, Permissions, Grants
(journal des accès accordés), Errors. À utiliser pour garder de gros rapports
petits, p. ex. -Category Permissions ou -Category Tree,LongPaths.
.EXAMPLE
.\filer-manager.ps1
Lance l'interface graphique.
.EXAMPLE
.\filer-manager.ps1 -Path "\\FILER01\Data","D:\Profiles" -Output C:\Reports\filer.html -NoGui
.EXAMPLE
.\filer-manager.ps1 -Path "D:\Shares" -Output filer.html -NoGui -GrantAccess
Analyse D:\Shares en accordant l'accès Administrators aux éléments refusés afin
que l'analyse puisse se terminer, puis annule ces modifications ensuite.
.EXAMPLE
.\filer-manager.ps1 -Path "\\NAS\Public" -Output filer.html -NoGui -ExcludeFolder '#recycle','@eaDir','Thumbs*' -ExcludeHidden
Exclut les dossiers système Synology (#recycle, @eaDir), tout dossier « Thumbs… »
et les dossiers masqués de l'analyse.
#>
[CmdletBinding()]
param(
[string[]]$Path,
[string]$Output,
[string]$CsvOutput,
[int]$MaxPathLength = 260,
[int]$PermissionDepth = 1,
[switch]$IncludeFilesInTree,
[string[]]$ExcludeFolder = @('#recycle', '@eaDir', '$RECYCLE.BIN'),
[switch]$ExcludeHidden,
[switch]$HideInheritedChildPerms,
[switch]$HideSystemPrincipals,
[switch]$GrantAccess,
[switch]$KeepGrants,
[switch]$NoGui,
[switch]$RevertPendingGrants,
[ValidateSet('All', 'Tree', 'LongPaths', 'Permissions', 'Grants', 'Errors')]
[string[]]$Category = @('All')
)
# ============================================================================
# CORE (GUI-independent). Kept as a string so it can be dot-sourced both here
# and inside a background runspace used by the GUI to stay responsive.
# ============================================================================
$CoreFunctions = @'
function Format-Bytes {
param([long]$Bytes)
if ($Bytes -ge 1TB) { '{0:N2} TB' -f ($Bytes / 1TB) }
elseif ($Bytes -ge 1GB) { '{0:N2} GB' -f ($Bytes / 1GB) }
elseif ($Bytes -ge 1MB) { '{0:N2} MB' -f ($Bytes / 1MB) }
elseif ($Bytes -ge 1KB) { '{0:N2} KB' -f ($Bytes / 1KB) }
else { "$Bytes B" }
}
function Test-IsElevated {
# True when the current process is running with Administrator rights.
try {
$id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
$pr = New-Object System.Security.Principal.WindowsPrincipal($id)
return $pr.IsInRole([System.Security.Principal.WindowsBuiltInRole]::Administrator)
} catch { return $false }
}
function Test-IsAccessDenied {
# Recognise an "access denied" failure across locales and PowerShell hosts.
param($ErrorRecord)
$ex = $ErrorRecord.Exception
if ($ex -is [System.UnauthorizedAccessException]) { return $true }
if ($ErrorRecord.CategoryInfo -and $ErrorRecord.CategoryInfo.Category -eq 'PermissionDenied') { return $true }
# A failure raised inside a .NET call reaches us wrapped in a
# MethodInvocationException, so the real cause is only visible on the base
# exception. Windows PowerShell 5.1 also reports some denials as a bare
# Win32Exception carrying ERROR_ACCESS_DENIED.
$base = $null
try { $base = $ex.GetBaseException() } catch { }
if ($base -is [System.UnauthorizedAccessException]) { return $true }
if ($base -is [System.ComponentModel.Win32Exception] -and $base.NativeErrorCode -eq 5) { return $true }
return $false
}
function Resolve-PrincipalSid {
# Best-effort translation of an ACE IdentityReference (an NTAccount or a
# SecurityIdentifier) to its SID string. Returns $null when unresolvable
# (e.g. an orphaned account from a deleted domain user).
param($IdentityReference)
try {
if ($IdentityReference -is [System.Security.Principal.SecurityIdentifier]) { return $IdentityReference.Value }
return $IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value
} catch {
# The reference may already be a raw SID string (unresolved account).
try { return (New-Object System.Security.Principal.SecurityIdentifier ([string]$IdentityReference)).Value } catch { return $null }
}
}
function Resolve-SidName {
# Friendly account name for a SID, falling back to the raw SID string when it
# cannot be translated (deleted account, broken trust, offline domain).
# Results are cached: a large scan meets the same handful of principals
# thousands of times and every miss costs an LSA / directory round trip.
param($Sid)
if (-not $Sid) { return '' }
if ($null -eq $script:FilerSidNameCache) { $script:FilerSidNameCache = @{} }
$key = [string]$Sid
if ($script:FilerSidNameCache.ContainsKey($key)) { return $script:FilerSidNameCache[$key] }
$name = $key
try {
if ($Sid -is [System.Security.Principal.SecurityIdentifier]) {
$name = $Sid.Translate([System.Security.Principal.NTAccount]).Value
}
else {
$name = (New-Object System.Security.Principal.SecurityIdentifier $key).Translate([System.Security.Principal.NTAccount]).Value
}
} catch { }
$script:FilerSidNameCache[$key] = $name
return $name
}
function Test-IsSystemPrincipal {
# True for well-known built-in / system accounts and groups, so the audit can
# focus on real business identities. Detection is by SID prefix (locale-
# independent), with a name-based fallback for the few cases where the SID
# could not be resolved. Examples: NT AUTHORITY\SYSTEM (S-1-5-18),
# BUILTIN\Administrators (S-1-5-32-544), CREATOR OWNER (S-1-3-*),
# NT SERVICE\TrustedInstaller (S-1-5-80-*).
param([string]$Identity, [string]$Sid)
if ($Sid) {
switch -Regex ($Sid) {
'^S-1-5-(18|19|20)$' { return $true } # SYSTEM / LOCAL SERVICE / NETWORK SERVICE
'^S-1-5-(6|9|17)$' { return $true } # SERVICE / Enterprise DCs / IUSR
'^S-1-5-32-' { return $true } # BUILTIN\* (Administrators, Users, ...)
'^S-1-5-(80|83|90|96)-' { return $true } # NT SERVICE / VM / Window Manager / Font driver
'^S-1-3-' { return $true } # CREATOR OWNER / CREATOR GROUP
}
}
# Name fallback: only when the SID could not be resolved (offline domain,
# broken trust). When a SID is known it is authoritative, so groups like
# Authenticated Users (S-1-5-11) are intentionally not treated as system even
# though their name carries the NT AUTHORITY prefix. Covers common
# English/French/German forms of the built-in domains and standalone principals.
if (-not $Sid -and $Identity) {
$id = $Identity.Trim()
foreach ($p in @('NT AUTHORITY\', 'AUTORITE NT\', "AUTORIT$([char]0xC9) NT\", 'NT-AUTORIT', 'BUILTIN\', 'NT SERVICE\', 'AUTORITE DE SECURITE')) {
if ($id.StartsWith($p, [System.StringComparison]::OrdinalIgnoreCase)) { return $true }
}
foreach ($e in @('SYSTEM', 'CREATOR OWNER', 'CREATOR GROUP', 'TrustedInstaller')) {
if ($id.Equals($e, [System.StringComparison]::OrdinalIgnoreCase)) { return $true }
}
}
return $false
}
function Grant-AdminAccess {
<# Seizes ownership for Administrators and grants BUILTIN\Administrators
FullControl on a single item (no recursion), so a denied path can be
scanned. Captures the original owner/ACL first (when readable) so the
change can be reverted later. Records every attempt in $Grants. Returns
$true when something was changed (so the caller can retry). #>
param(
[string]$Path,
[string]$Reason,
[System.Collections.ArrayList]$Grants,
[System.Collections.ArrayList]$ScanErrors
)
# BUILTIN\Administrators well-known SID - locale-independent (the group is
# named differently on non-English systems).
$adminSid = 'S-1-5-32-544'
# Don't act twice on the same path.
foreach ($g in $Grants) { if ($g.Path -eq $Path) { return $g.Success } }
# Capture the original state for a possible revert (may be unreadable).
$origSddl = $null; $origOwner = $null
try {
$a = Get-Acl -LiteralPath $Path -ErrorAction Stop
$origSddl = $a.Sddl; $origOwner = [string]$a.Owner
} catch { }
$isDir = $true
try { $isDir = [bool]((Get-Item -LiteralPath $Path -Force -ErrorAction Stop).PSIsContainer) } catch { }
$changes = New-Object System.Collections.ArrayList
$errText = $null
# 1) Seize ownership for Administrators (icacls enables the needed privilege
# itself and, unlike takeown, has no locale-specific confirmation prompt).
$null = & icacls.exe $Path /setowner "*$adminSid" /C /Q 2>&1
if ($LASTEXITCODE -eq 0) { [void]$changes.Add('Propriétaire défini -> Administrators') }
else { $errText = "setowner a échoué (code $LASTEXITCODE)" }
# 2) Grant Administrators FullControl (inheritable on directories).
$perm = if ($isDir) { "*${adminSid}:(OI)(CI)F" } else { "*${adminSid}:F" }
$null = & icacls.exe $Path /grant $perm /C /Q 2>&1
if ($LASTEXITCODE -eq 0) { [void]$changes.Add('Administrators -> FullControl accordé') }
else { if ($errText) { $errText += '; ' }; $errText += "grant a échoué (code $LASTEXITCODE)" }
$success = ($changes.Count -gt 0)
[void]$Grants.Add([pscustomobject]@{
Path = $Path
IsDir = $isDir
Reason = $Reason
Changes = ($changes -join '; ')
OriginalOwner = $origOwner
OriginalSddl = $origSddl
Success = $success
Error = $errText
Reverted = $false
RevertError = $null
})
# Persist before returning: from here on the change is live on disk, so it
# has to be recoverable even if this process never reaches Restore-Grants.
if ($success) { Save-FilerGrantJournal -Grants $Grants }
if (-not $success -and $errText) {
[void]$ScanErrors.Add([pscustomobject]@{ Path = $Path; Error = "Octroi automatique échoué : $errText" })
}
return $success
}
function Restore-Grants {
<# Reverts the changes made by Grant-AdminAccess, children before parents.
Restores the full original security descriptor (owner + ACL) when it was
captured; otherwise removes only the Administrators ACE we added. #>
param(
[System.Collections.ArrayList]$Grants,
[System.Collections.ArrayList]$ScanErrors,
[hashtable]$Progress
)
$adminSid = 'S-1-5-32-544'
for ($i = $Grants.Count - 1; $i -ge 0; $i--) {
$g = $Grants[$i]
if (-not $g.Success) { continue }
if ($Progress) { $Progress.Status = "Annulation de l'accès : $($g.Path)" }
$done = $false; $err = $null
if ($g.OriginalSddl) {
try {
if ($g.IsDir) { $sec = New-Object System.Security.AccessControl.DirectorySecurity }
else { $sec = New-Object System.Security.AccessControl.FileSecurity }
$sec.SetSecurityDescriptorSddlForm($g.OriginalSddl)
Set-Acl -LiteralPath $g.Path -AclObject $sec -ErrorAction Stop
$done = $true
} catch { $err = "Échec de la restauration Set-Acl : $($_.Exception.Message)" }
}
if (-not $done) {
# Best-effort fallback: drop the ACE we added and put the owner back.
try {
$null = & icacls.exe $g.Path /remove:g "*$adminSid" /C /Q 2>&1
if ($g.OriginalOwner) { $null = & icacls.exe $g.Path /setowner $g.OriginalOwner /C /Q 2>&1 }
if (-not $g.OriginalSddl) {
$done = $true
$err = "l'ACL d'origine était illisible ; seul l'ACE Administrators ajouté a été supprimé"
}
} catch { if ($err) { $err += '; ' }; $err += "Repli icacls échoué : $($_.Exception.Message)" }
}
$g.Reverted = $done
$g.RevertError = $err
if ($err) { [void]$ScanErrors.Add([pscustomobject]@{ Path = $g.Path; Error = "Annulation : $err" }) }
}
Save-FilerGrantJournal -Grants $Grants
}
function Get-FilerGrantJournalDir {
# Where the pending-grant journals live: one file per process id.
$dir = Join-Path ([string]$env:LOCALAPPDATA) 'FilerManager'
if (-not (Test-Path -LiteralPath $dir)) {
try { $null = New-Item -ItemType Directory -Path $dir -Force -ErrorAction Stop } catch { return $null }
}
return $dir
}
function Save-FilerGrantJournal {
<# Mirrors the not-yet-reverted grants to disk. Without it, losing the process
between a grant and Restore-Grants - the GUI closed mid-scan, a crash, a
logoff - would leave Administrators as owner with FullControl on the
scanned folders and no record that Filer Manager put it there. Best effort
by design: a journal failure must never abort a scan. The file is removed
as soon as nothing is pending. #>
param([System.Collections.ArrayList]$Grants)
if (-not $script:FilerGrantJournalPath) { return }
try {
$pending = @($Grants | Where-Object { $_.Success -and -not $_.Reverted } | ForEach-Object {
[pscustomobject]@{
Path = [string]$_.Path
IsDir = [bool]$_.IsDir
OriginalOwner = [string]$_.OriginalOwner
OriginalSddl = [string]$_.OriginalSddl
}
})
if ($pending.Count -eq 0) {
Remove-Item -LiteralPath $script:FilerGrantJournalPath -Force -ErrorAction SilentlyContinue
return
}
# Wrapped in an object: ConvertTo-Json collapses a one-element array.
$doc = [pscustomobject]@{
Computer = [string]$env:COMPUTERNAME
Pid = $PID
Written = (Get-Date).ToString('o')
Grants = $pending
}
(ConvertTo-Json -InputObject $doc -Depth 4) |
Set-Content -LiteralPath $script:FilerGrantJournalPath -Encoding UTF8 -ErrorAction Stop
} catch { }
}
function Get-FilerPendingGrantJournal {
<# Journals left behind by a run that never reverted. A journal whose owning
process is still alive is skipped - that scan is running and will clean up
after itself. A recycled process id can therefore delay a recovery, never
break one: the file simply stays until a later run finds the id free. #>
$dir = Get-FilerGrantJournalDir
if (-not $dir) { return @() }
$out = New-Object System.Collections.ArrayList
foreach ($f in @(Get-ChildItem -LiteralPath $dir -Filter 'grants-*.json' -File -ErrorAction SilentlyContinue)) {
$doc = $null
try { $doc = (Get-Content -LiteralPath $f.FullName -Raw -ErrorAction Stop) | ConvertFrom-Json } catch { continue }
$rows = @($doc.Grants | Where-Object { $_ -and $_.Path })
if ($rows.Count -eq 0) { Remove-Item -LiteralPath $f.FullName -Force -ErrorAction SilentlyContinue; continue }
$owner = 0
try { $owner = [int]$doc.Pid } catch { }
if ($owner -eq $PID) { continue }
if ($owner -gt 0) {
$alive = $null
try { $alive = Get-Process -Id $owner -ErrorAction Stop } catch { }
if ($alive) { continue }
}
[void]$out.Add([pscustomobject]@{ File = $f.FullName; Grants = $rows; Written = [string]$doc.Written })
}
return $out.ToArray()
}
function Restore-FilerPendingGrants {
<# Replays one orphaned journal through Restore-Grants, deleting it only once
every entry came back. Returns a small report. #>
param([Parameter(Mandatory)] $Journal)
$grants = New-Object System.Collections.ArrayList
foreach ($g in @($Journal.Grants)) {
[void]$grants.Add([pscustomobject]@{
Path = [string]$g.Path
IsDir = [bool]$g.IsDir
Reason = 'journal'
Changes = ''
OriginalOwner = [string]$g.OriginalOwner
OriginalSddl = [string]$g.OriginalSddl
Success = $true
Error = $null
Reverted = $false
RevertError = $null
})
}
$errs = New-Object System.Collections.ArrayList
# Blank the journal path while replaying: Restore-Grants must not rewrite the
# very file we are consuming.
$saved = $script:FilerGrantJournalPath
$script:FilerGrantJournalPath = $null
try { Restore-Grants -Grants $grants -ScanErrors $errs -Progress $null }
finally { $script:FilerGrantJournalPath = $saved }
$failed = @($grants | Where-Object { -not $_.Reverted })
if ($failed.Count -eq 0) { Remove-Item -LiteralPath $Journal.File -Force -ErrorAction SilentlyContinue }
return [pscustomobject]@{
Total = $grants.Count
Reverted = @($grants | Where-Object { $_.Reverted }).Count
Failed = $failed.Count
Errors = @($errs)
}
}
function Test-IsExcludedFolder {
# True when a directory entry should be skipped from the analysis. A folder is
# excluded when its name matches one of the (wildcard, case-insensitive)
# patterns - e.g. '#recycle', '@eaDir', 'Thumbs*' - or when -ExcludeHidden is
# set and the directory carries the Hidden attribute. Exclusions apply to
# descendants only; a scan root is always analysed even if it would match.
param($Entry, [string[]]$Patterns, [bool]$ExcludeHidden)
if ($ExcludeHidden) {
try { if (($Entry.Attributes -band [System.IO.FileAttributes]::Hidden) -ne 0) { return $true } } catch { }
}
if ($Patterns) {
$name = [string]$Entry.Name
foreach ($pat in $Patterns) {
if ([string]::IsNullOrWhiteSpace($pat)) { continue }
if ($name -like $pat) { return $true }
}
}
return $false
}
function Test-IsReparsePoint {
# True for a junction, a directory symlink or any other reparse point. Those
# must never be descended into: a link that points at one of its own
# ancestors makes the walk recurse until the stack (or the path length) gives
# out, and a lateral one counts the very same bytes twice. They are still
# reported as an entry, just never followed.
param($Entry)
try { return (($Entry.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) } catch { return $false }
}
function Expand-FilerShortPath {
<# Expands 8.3 short components of a path to their long form. Resolve-Path
keeps them as-is and [IO.Path]::GetFullPath expands them, so neither is a
reliable answer on its own; GetLongPathNameW is authoritative and also
accepts an extended-length path. #>
param([string]$Path)
if ([string]::IsNullOrWhiteSpace($Path)) { return $Path }
if (-not ('FilerManager.LongPath' -as [type])) { try { Initialize-FilerNetApi } catch { } }
if ('FilerManager.LongPath' -as [type]) {
try { return [FilerManager.LongPath]::ExpandShort($Path) } catch { }
}
return $Path
}
function Get-FilerChildEntry {
<# Directory listing that is not bounded by MAX_PATH, used by every part of
the scan that walks a tree. Returns Entries / ErrorCode / ErrorMessage
instead of throwing, so the caller can tell "access denied" (code 5) from
"not there" without unwrapping a MethodInvocationException.
Entries carry Name / FullPath / Attributes / IsDirectory / IsReparsePoint /
Length, which is the subset of FileSystemInfo the scan actually used, so
Test-IsExcludedFolder and Test-IsReparsePoint work on them unchanged.
Get-ChildItem remains as a fallback in case the P/Invoke shim cannot be
compiled. #>
param([string]$Path)
if (-not ('FilerManager.LongPath' -as [type])) { try { Initialize-FilerNetApi } catch { } }
if ('FilerManager.LongPath' -as [type]) {
try { return [FilerManager.LongPath]::GetEntries($Path) } catch { }
}
try {
$out = New-Object System.Collections.ArrayList
foreach ($i in @(Get-ChildItem -LiteralPath $Path -Force -ErrorAction Stop)) {
$isDir = [bool]$i.PSIsContainer
$len = [long]0
if (-not $isDir) { try { $len = [long]$i.Length } catch { $len = [long]0 } }
[void]$out.Add([pscustomobject]@{
Name = [string]$i.Name
FullPath = [string]$i.FullName
Attributes = $i.Attributes
IsDirectory = $isDir
IsReparsePoint = (($i.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0)
Length = $len
})
}
return [pscustomobject]@{ Entries = $out.ToArray(); ErrorCode = 0; ErrorMessage = $null }
}
catch {
$code = if (Test-IsAccessDenied $_) { 5 } else { -1 }
return [pscustomobject]@{ Entries = @(); ErrorCode = $code; ErrorMessage = $_.Exception.GetBaseException().Message }
}
}
function Get-FolderNode {
<# Recursively builds a size tree. Accumulates long paths and errors via
synchronized collections passed by the caller. #>
param(
[string]$Path,
[int]$MaxLen,
[System.Collections.ArrayList]$LongPaths,
[System.Collections.ArrayList]$ScanErrors,
[hashtable]$Progress,
[int]$Depth = 0
)
$name = [System.IO.Path]::GetFileName($Path.TrimEnd('\'))
if ([string]::IsNullOrEmpty($name)) { $name = $Path } # e.g. a drive root
$node = [ordered]@{
Name = $name
FullPath = $Path
Size = [long]0
FileCount = 0
FolderCount = 0
Depth = $Depth
Children = New-Object System.Collections.ArrayList
}
if ($Progress) { $Progress.Status = "Analyse : $Path" }
if ($Path.Length -ge $MaxLen) {
[void]$LongPaths.Add([pscustomobject]@{ Type = 'Dossier'; Length = $Path.Length; Path = $Path })
}
$entries = $null
$granted = $false
while ($true) {
$listing = Get-FilerChildEntry -Path $Path
if ($listing.ErrorCode -eq 0) { $entries = $listing.Entries; break }
if ($GrantAccessFlag -and -not $granted -and $listing.ErrorCode -eq 5) {
$granted = $true
if ($Progress) { $Progress.Status = "Octroi de l'accès : $Path" }
if (Grant-AdminAccess -Path $Path -Reason 'énumérer le dossier' -Grants $GrantList -ScanErrors $ScanErrors) {
continue # retry once, now that access has been granted
}
}
[void]$ScanErrors.Add([pscustomobject]@{ Path = $Path; Error = [string]$listing.ErrorMessage })
return [pscustomobject]$node
}
foreach ($entry in $entries) {
if ($entry.IsDirectory) {
if (Test-IsExcludedFolder -Entry $entry -Patterns $ExcludeFolderFlag -ExcludeHidden $ExcludeHiddenFlag) { continue }
if (Test-IsReparsePoint -Entry $entry) {
# Junction / directory symlink: recorded as a leaf, never walked,
# and contributing no size (the bytes belong to the link target).
$node.FolderCount += 1
[void]$node.Children.Add([pscustomobject]@{
Name = $entry.Name; FullPath = $entry.FullPath; Size = [long]0
FileCount = 0; FolderCount = 0; Depth = $Depth + 1; IsLink = $true
Children = (New-Object System.Collections.ArrayList)
})
if ($entry.FullPath.Length -ge $MaxLen) {
[void]$LongPaths.Add([pscustomobject]@{ Type = 'Lien'; Length = $entry.FullPath.Length; Path = $entry.FullPath })
}
continue
}
$child = Get-FolderNode -Path $entry.FullPath -MaxLen $MaxLen `
-LongPaths $LongPaths -ScanErrors $ScanErrors `
-Progress $Progress -Depth ($Depth + 1)
$node.Size += $child.Size
$node.FileCount += $child.FileCount
$node.FolderCount += 1 + $child.FolderCount
[void]$node.Children.Add($child)
}
else {
$len = [long]0
try { $len = [long]$entry.Length } catch { $len = [long]0 }
$node.Size += $len
$node.FileCount += 1
if ($entry.FullPath.Length -ge $MaxLen) {
[void]$LongPaths.Add([pscustomobject]@{ Type = 'Fichier'; Length = $entry.FullPath.Length; Path = $entry.FullPath })
}
if ($IncludeFilesInTreeFlag) {
[void]$node.Children.Add([pscustomobject]@{
Name = $entry.Name; FullPath = $entry.FullPath; Size = $len
FileCount = 0; FolderCount = 0; Depth = $Depth + 1; IsFile = $true
Children = (New-Object System.Collections.ArrayList)
})
}
}
}
return [pscustomobject]$node
}
function Get-FolderPermissions {
param(
[string]$Path,
[int]$Depth,
[System.Collections.ArrayList]$ScanErrors,
[int]$Current = 0
)
$results = New-Object System.Collections.ArrayList
$granted = $false
while ($true) {
try {
$acl = Get-Acl -LiteralPath $Path -ErrorAction Stop
# Read the owner and the ACEs as raw SIDs, then translate each name on its
# own. The NTAccount form of these APIs ($acl.Owner / $acl.Access) throws
# IdentityNotMappedException as soon as ONE principal is unresolvable - a
# single orphaned SID would otherwise cost us the whole folder's ACL.
$ownerSid = $null
try { $ownerSid = $acl.GetOwner([System.Security.Principal.SecurityIdentifier]) } catch { }
$owner = Resolve-SidName $ownerSid
foreach ($ace in $acl.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])) {
[void]$results.Add([pscustomobject]@{
Folder = $Path
Owner = $owner
Identity = (Resolve-SidName $ace.IdentityReference)
Sid = [string]$ace.IdentityReference
Rights = [string]$ace.FileSystemRights
Type = [string]$ace.AccessControlType
Inherited = $ace.IsInherited
})
}
break
}
catch {
if ($GrantAccessFlag -and -not $granted -and (Test-IsAccessDenied $_)) {
$granted = $true
if (Grant-AdminAccess -Path $Path -Reason 'lire les permissions' -Grants $GrantList -ScanErrors $ScanErrors) {
continue # retry once, now that the ACL is readable
}
}
[void]$ScanErrors.Add([pscustomobject]@{ Path = $Path; Error = "ACL : $($_.Exception.Message)" })
break
}
}
if ($Current -lt $Depth) {
$subDirs = @()
$listing = Get-FilerChildEntry -Path $Path
if ($listing.ErrorCode -eq 0) { $subDirs = @($listing.Entries | Where-Object { $_.IsDirectory }) }
foreach ($d in $subDirs) {
if (Test-IsExcludedFolder -Entry $d -Patterns $ExcludeFolderFlag -ExcludeHidden $ExcludeHiddenFlag) { continue }
if (Test-IsReparsePoint -Entry $d) { continue } # never follow a junction / symlink
$child = Get-FolderPermissions -Path $d.FullPath -Depth $Depth -ScanErrors $ScanErrors -Current ($Current + 1)
foreach ($r in $child) { [void]$results.Add($r) }
}
}
return $results
}
function Invoke-FilerScan {
param(
[string[]]$Paths,
[int]$MaxPathLength = 260,
[int]$PermissionDepth = 1,
[bool]$IncludeFilesInTree = $false,
[string[]]$ExcludeFolder = @(),
[bool]$ExcludeHidden = $false,
[bool]$GrantAccess = $false,
[bool]$RevertGrants = $true,
[hashtable]$Progress
)
$script:IncludeFilesInTreeFlag = $IncludeFilesInTree
$script:ExcludeFolderFlag = $ExcludeFolder
$script:ExcludeHiddenFlag = $ExcludeHidden
$script:GrantAccessFlag = $GrantAccess
$script:GrantList = New-Object System.Collections.ArrayList
# Arm the on-disk journal only when we actually intend to revert: with
# -KeepGrants the changes are meant to stay, so there is nothing to recover.
$script:FilerGrantJournalPath = $null
if ($GrantAccess -and $RevertGrants) {
$jdir = Get-FilerGrantJournalDir
if ($jdir) { $script:FilerGrantJournalPath = Join-Path $jdir ("grants-{0}.json" -f $PID) }
}
# Compile the P/Invoke shim up front: Get-FilerChildEntry needs
# FilerManager.LongPath to get past MAX_PATH, and doing it once here keeps the
# cost off the recursion.
try { Initialize-FilerNetApi } catch { }
$longPaths = New-Object System.Collections.ArrayList
$scanErrors = New-Object System.Collections.ArrayList
$permissions = New-Object System.Collections.ArrayList
$roots = New-Object System.Collections.ArrayList
# Drive inventory is only needed when a root is given as a drive letter; it is
# resolved once and shared, since a network path can be slow to interrogate.
$inventory = $null
if (@($Paths | Where-Object { $_ -match '^[A-Za-z]:' }).Count -gt 0) {
$inventory = Get-FilerDriveInventory
}
foreach ($rawPath in $Paths) {
# A mapped drive letter is rewritten to its UNC target when the mapping is
# missing from this process token (typical for an elevated run: UAC gives
# each token its own set of network drives).
$resolved = Resolve-FilerScanPath -Path $rawPath -Inventory $inventory
$p = $resolved.Path
if (-not $p) {
[void]$scanErrors.Add([pscustomobject]@{ Path = $rawPath; Error = 'Chemin vide' })
continue
}
if ($Progress -and $resolved.Rewritten) { $Progress.Status = "Chemin réseau : $rawPath -> $p" }
$reach = Test-FilerPathReachable -Path $p -TimeoutSeconds 20
if (-not $reach.Exists) {
$msg = 'Chemin introuvable'
if ($reach.TimedOut) {
$msg = 'Serveur injoignable (délai dépassé)'
}
elseif ($resolved.Letter -and -not $resolved.Mounted) {
$msg = if ($resolved.Unc) {
"Lecteur $($resolved.Letter) non monté dans cette session ; cible $($resolved.Unc) inaccessible"
} else {
"Lecteur $($resolved.Letter) non monté dans cette session et cible UNC inconnue (mappez-le ou saisissez le chemin \\serveur\partage)"
}
}
elseif ($resolved.IsNetwork) {
$msg = 'Chemin réseau inaccessible (hors ligne ou identifiants manquants)'
}
if ($reach.Error) { $msg += " : $($reach.Error)" }
[void]$scanErrors.Add([pscustomobject]@{ Path = $rawPath; Error = $msg })
continue
}
# Canonicalise the root once. Every child path is derived from this
# string, and every length compared against -MaxPathLength is measured on
# it, so an 8.3 alias here would understate how long the real paths are.
# ProviderPath, not Path: on a UNC root the latter comes back in
# provider-qualified form ("Microsoft.PowerShell.Core\FileSystem::\\srv\
# share"), which no Win32 call can open - the scan then found nothing.
$fullPath = $p
try {
$rp = Resolve-Path -LiteralPath $p -ErrorAction Stop
$cand = [string]$rp.ProviderPath
if ([string]::IsNullOrWhiteSpace($cand)) { $cand = [string]$rp.Path }
if ($cand) { $fullPath = $cand }
} catch { }
$fullPath = Expand-FilerShortPath -Path $fullPath
$node = Get-FolderNode -Path $fullPath -MaxLen $MaxPathLength `
-LongPaths $longPaths -ScanErrors $scanErrors -Progress $Progress
[void]$roots.Add($node)
if ($Progress) { $Progress.Status = "Lecture des permissions : $fullPath" }
$perms = Get-FolderPermissions -Path $fullPath -Depth $PermissionDepth -ScanErrors $scanErrors
foreach ($r in $perms) { [void]$permissions.Add($r) }
}
# Revert the access we granted, once the scan (and ACL reads) are done.
if ($GrantAccess -and $RevertGrants -and $script:GrantList.Count -gt 0) {
if ($Progress) { $Progress.Status = 'Annulation des accès accordés...' }
Restore-Grants -Grants $script:GrantList -ScanErrors $scanErrors -Progress $Progress
}
$totalSize = ($roots | Measure-Object -Property Size -Sum).Sum
if (-not $totalSize) { $totalSize = 0 }
$grantsMade = @($script:GrantList | Where-Object { $_.Success })
return [pscustomobject]@{
Roots = $roots
LongPaths = ($longPaths | Sort-Object Length -Descending)
Permissions = $permissions
Grants = $script:GrantList
Errors = $scanErrors
Settings = [pscustomobject]@{
MaxPathLength = $MaxPathLength
PermissionDepth = $PermissionDepth
IncludeFilesInTree = $IncludeFilesInTree
ExcludeFolder = @($ExcludeFolder | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
ExcludeHidden = $ExcludeHidden
GrantAccess = $GrantAccess
RevertGrants = $RevertGrants
}
Stats = [pscustomobject]@{
TotalSize = [long]$totalSize
TotalFiles = ($roots | Measure-Object -Property FileCount -Sum).Sum
TotalFolders = ($roots | Measure-Object -Property FolderCount -Sum).Sum
LongPaths = $longPaths.Count
Errors = $scanErrors.Count
Grants = $grantsMade.Count
}
Computer = $env:COMPUTERNAME
GeneratedAt = (Get-Date)
}
}
function Get-FilerRootPathSet {
# Case-insensitive set of the scan-root full paths. Used to decide which
# permission rows sit on a scan root (vs. a child folder).
param($Scan)
$set = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::OrdinalIgnoreCase)
foreach ($r in $Scan.Roots) { [void]$set.Add([string]$r.FullPath) }
return $set
}
function Select-FilerPerms {
# Returns the scan's permission ACEs, optionally dropping inherited ACEs that
# sit on a child folder and/or ACEs held by well-known system principals.
# Inherited ACEs on the scan roots are always kept: a root's parent is outside
# the scan, so those entries are the only record of the permissions in effect there.
param($Scan, [bool]$HideInheritedChildPerms, [bool]$HideSystemPrincipals)
$rows = @($Scan.Permissions)
if ($HideInheritedChildPerms) {
$roots = Get-FilerRootPathSet -Scan $Scan
$rows = @($rows | Where-Object { (-not $_.Inherited) -or $roots.Contains([string]$_.Folder) })
}
if ($HideSystemPrincipals) {
$rows = @($rows | Where-Object { -not (Test-IsSystemPrincipal -Identity $_.Identity -Sid $_.Sid) })
}
return $rows
}
function ConvertTo-FilerHtmlReport {
param(
[Parameter(Mandatory)] $Scan,
[Parameter(Mandatory)] [string]$Path,
# Which report categories to include. 'All' (default) emits everything;
# otherwise pass any combination of Tree, LongPaths, Permissions, Grants, Errors.
[ValidateSet('All', 'Tree', 'LongPaths', 'Permissions', 'Grants', 'Errors')]
[string[]]$Categories = @('All'),
# When set, inherited permissions on child folders are omitted (roots keep theirs).
[bool]$HideInheritedChildPerms = $false,
# When set, ACEs held by well-known system/built-in principals are omitted.
[bool]$HideSystemPrincipals = $false
)
function _enc([string]$s) { [System.Net.WebUtility]::HtmlEncode($s) }
# Resolve the requested categories into per-section switches.
$all = ($Categories -contains 'All') -or ($Categories.Count -eq 0)
$wantTree = $all -or ($Categories -contains 'Tree')
$wantLong = $all -or ($Categories -contains 'LongPaths')
$wantPerm = $all -or ($Categories -contains 'Permissions')
$wantGrants = $all -or ($Categories -contains 'Grants')
$wantErrors = $all -or ($Categories -contains 'Errors')
$sb = New-Object System.Text.StringBuilder
# ---- recursive tree renderer (folders sorted largest-first) ----
function _renderNode {
param($Node, [long]$ParentSize, [System.Text.StringBuilder]$Out)
$pct = if ($ParentSize -gt 0) { [math]::Round(($Node.Size / $ParentSize) * 100, 1) } else { 100 }
$sizeStr = Format-Bytes $Node.Size
$isFile = ($Node.PSObject.Properties.Name -contains 'IsFile' -and $Node.IsFile)
$isLink = ($Node.PSObject.Properties.Name -contains 'IsLink' -and $Node.IsLink)
$icon = if ($isLink) { '🔗' } elseif ($isFile) { '📄' } else { '📁' }
$meta = if ($isLink) { " lien (non parcouru)" }
elseif ($isFile) { '' }
else { " $($Node.FolderCount) dossiers, $($Node.FileCount) fichiers" }
$kids = @($Node.Children | Where-Object { $_ } )
$summary = "$icon $(_enc $Node.Name)$sizeStr" +
"$pct%$meta"
if ($kids.Count -gt 0) {
$open = if ($Node.Depth -eq 0) { ' open' } else { '' }
[void]$Out.Append("$summary
Éléments qui étaient refusés, sur lesquels la propriété/le FullControl Administrators a été appliqué afin de pouvoir les analyser.
Mode : $(if ($Scan.Settings.RevertGrants) { "annuler après l'analyse" } else { 'conserver les modifications' }).