README.md

ShareSurfer

ShareSurfer is a read-only PowerShell-first toolkit for making complex Windows file-share access understandable. It collects share permissions, filesystem ACLs, ownership, inheritance state, identity/group context, org attributes, and migration-readiness findings into CSVs, reports, and an offline dashboard.

It is built for controlled environments:

• PowerShell 5.1 collector module under src/ShareSurfer
• Normalized CSV exports for Excel, Power BI, and downstream review
• Offline report.html plus optional packaged standalone dashboard
• Windows/AD lab fixtures for repeatable validation
• Export validation and redacted support bundles

How ShareSurfer Works

ShareSurfer does not change permissions, approve access, or migrate data. It collects evidence, normalizes it, enriches it, and gives operators and business owners safer ways to review the current state.

In ShareSurfer, Owner means the mapped business or data reviewer for a share, folder, or group of related paths. That is separate from the Windows NTFS owner field in items.csv.

Step	What happens	Visual
Evidence pipeline	Share, ACL, owner, inheritance, identity, and finding evidence becomes normalized outputs.
Share gate plus NTFS	Share permissions and file/folder ACLs are reviewed together.
Identity context	Groups expand, members enrich, manager chains are followed, and -ObsAttribute records OBS/OID context.
Migration Discovery	Related shares and folders are grouped by owner, business unit, OBS, manager chain, paths, and group overlap.
Trust review	evidence_confidence.csv and diagnostics explain partial data, provider fallback, and rerun needs.
Safe support handoff	Redacted support bundles preserve troubleshooting shape without exposing raw identities and paths.

For the fuller explanation, use the visual field guide.

Start Here

For the first real run:

1. Download ShareSurfer-0.1.0-pre.43.zip and its SHA256 file from the current prerelease. If that tag is not visible, use the latest published prerelease and substitute its version in the paths below.

2. Extract to C:\ so the release root is C:\ShareSurfer-0.1.0-pre.43\.

3. Recursively unblock extracted PowerShell files:

   $releaseRoot = 'C:\ShareSurfer-0.1.0-pre.43'
   Get-ChildItem -LiteralPath $releaseRoot -Recurse -File |
     Where-Object { $_.Extension -in '.ps1', '.psm1', '.psd1' } |
     Unblock-File

   This is the cleanest no-prompt path. If you skip this and run .\Start-ShareSurfer.ps1 directly, Windows may still show one prompt for the launcher because the launcher cannot unblock itself before it starts. After you choose Run once, the launcher attempts the same recursive unblock before importing the module.

4. For the guided startup path, run the release-root launcher:

   powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "$releaseRoot\Start-ShareSurfer.ps1"

   It recursively unblocks ShareSurfer PowerShell files, imports the module, and opens one goal-based home screen. Press Enter to choose Start a first scan (recommended). The other choices are Run a saved scan, Review existing results, Add ownership or HR data, Advanced tools, and Exit. An action that is not ready remains visible with a short reason but cannot be selected.

   A first scan asks for the UNC share or folder first, then whether review stays on this computer or moves to a separate review computer. Collection still runs on the collector; the separate-computer choice records that validated evidence must later use the approved transfer process. ShareSurfer proposes recommended defaults: folders only, compact ACL output, identity enrichment and permission diagnostics enabled, ownership inputs deferred, and conventional paths generated automatically. Choose Continue with recommended settings or Customize technical settings, then review the plain-language plan. Choose Run now, Save plan and return home, or Show technical command; Back and Cancel remain available. Generated files are summarized by path, while full JSON, scripts, and exact commands stay secondary to the plain-language review. If saved startup files already exist, ShareSurfer asks before replacing them and defaults to keeping them.

5. For a normal first scan, accept the recommended settings. Use Customize only when your environment needs different scan, directory, ownership, or output settings.

6. At the final review, choose Run now to collect evidence or Save plan and return home to inspect and run it later.

7. After collection, always run Test-ShareSurferExport. Package the standalone dashboard only from an export that passed current validation.

8. Review the stop gates before owner signoff or migration planning.

New operators should start with the first-run guide and keep the command recipes nearby. The default interface uses reliable numbered prompts for Windows PowerShell 5.1; use -ConsoleMode Enhanced only when you specifically want arrow-key selection in a console that handles it well, and use -ConsoleMode Plain for redirected or locked-down consoles. Advanced operators can still run Start-ShareSurferStartup directly or pass -ConfigPath to replay a saved startup configuration without the home screen. The generated sharesurfer-startup.config.json, operator-assistant.plan.json, and operator-assistant-rerun.ps1 preserve the existing reviewable automation path.

Pause Before Owner Signoff

Stop or document the gap before business-owner approval when any of these are true:

Stop gate	Where to look	Meaning
Missing or suspicious share-level permissions	share-permission-diagnostics\share_permission_diagnostics.md, share_permission_diagnostics.csv, collection_errors.csv	The share may be reachable, but ShareSurfer may not have proven share-level permissions or parsed security descriptor evidence.
Partial data or collection errors	evidence_confidence.csv, shares.csv, collection_errors.csv, dashboard Diagnostics	The export may be structurally valid but incomplete.
Wrong or missing OBS attribute	scan_manifest.csv, identities.csv, org_chains.csv	Reviewer routing may be blank or wrong.
Template dashboard confusion	interface\standalone-dashboard\dist\index.html versus $exportPath\standalone-dashboard\index.html	Release dashboard assets are templates; real review requires a packaged export.
Evidence confidence or protocol readiness blockers	evidence_confidence.csv, port_protocol_targets.csv, port_protocol_checks.csv, fileshare_connectivity_checks.csv	Network reachability does not prove ShareSurfer could read security descriptors or ACL evidence.
Missing owner or business-unit mapping	owner_mappings.csv, owner_review_packets.csv, owner_risk_pivots.csv	Evidence may be collected, but the business reviewer may not know why they own it.

Command Inventory by Workflow

Workflow	Commands and scripts
Guided first run	Start-ShareSurfer.ps1, Start-ShareSurfer, Start-ShareSurferStartup, Start-ShareSurferOperatorAssistant
Lab and fixture planning	New-ShareSurferLabFixture, scripts\Invoke-ShareSurferLabValidation.ps1
Scan collection	Invoke-ShareSurferScan
Optional readiness and diagnostics	Invoke-ShareSurferOpenFileAssessment, Invoke-ShareSurferPortProtocolAssessment, Invoke-ShareSurferFileShareConnectivityAssessment, Invoke-ShareSurferSharePermissionDiagnostic
Ownership import and mapping	Test-ShareSurferOwnershipSource, New-ShareSurferOwnershipMappingProfile, Import-ShareSurferOwnershipSource, Join-ShareSurferOwnershipSources, New-ShareSurferOwnerMappingDraft, Test-ShareSurferOwnerMapping
Review decisions	New-ShareSurferReviewDecisionDraft, Import-ShareSurferReviewDecisions
Validation and reports	Test-ShareSurferExport, ConvertTo-ShareSurferReport, scripts\New-ShareSurferStandaloneDashboard.ps1, optional scripts\Start-ShareSurferNativeViewer.ps1
Support and release packaging	New-ShareSurferSupportBundle, scripts\New-ShareSurferRelease.ps1, scripts\Test-ShareSurferReleaseReadiness.ps1

Basic Use Cases

Use case	Start here	Main outputs
First business-owner review	Scan one known share with owner mapping	owner_review_packets.csv, owner_risk_pivots.csv, report.html
Flexible ownership import and enrichment	Normalize HR, employee, OBS, OID, project, or owner CSVs	normalized-ownership.csv, ownership-enrichment.csv, ownership-import.definition.json
Migration discovery	Scan related shares with file/folder evidence and owner mappings	related_data_areas.csv, long-path findings, inheritance breaks, conflicts
Hot folder activity review	Add open-file assessment	open_file_summary.csv, open_file_samples.csv
Port and protocol readiness	Add port/protocol assessment	port_protocol_targets.csv, port_protocol_checks.csv
File-share collection capability troubleshooting	Add file-share connectivity assessment	fileshare_connectivity_targets.csv, fileshare_connectivity_checks.csv, redacted LLM-ready summary
Evidence confidence review	Validate completeness before approval	evidence_confidence.csv, collection_errors.csv
Nonpermissive collector workflow	Collect on a locked-down host, then transfer the export	Validated CSV folder, report.html, standalone dashboard, optional native viewer
Broad admin or HelpDesk access cleanup	Provide discounted principals	Visible access evidence that does not inflate migration relatedness
Support or bug report	Create a redacted support bundle	Redacted CSVs, manifests, optional redacted report

Workflow Guides

Use workflow-guides.md for the step-by-step version and workflow-visuals.md for the visual index.

Ownership And OBS Data

Use the admin ownership import guide when HR, employee, OBS, OID, project, or owner facts live in CSVs with unexpected headers. Use the ownership data thinking guide when you need to decide what Owner, OBS, service-account-like rows, group evidence, and coverage targets really mean. Use the shorter ownership CSV ingest quick reference when another team just needs copy/paste instructions.

Key ideas:

• Join-ShareSurferOwnershipSources can combine one or more CSVs before the scan.
• Add -IncludeContextGraph when one source describes projects, apps, path prefixes, groups, or OBS/business context instead of people. This writes ownership_context.csv, ownership_relationships.csv, and ownership_import_manifest.csv beside ownership-enrichment.csv.
• If a source has employee ID or employee number, ShareSurfer can use it to match AD accounts and fill account, mail, title, office, manager, and OBS fields when available.
• Use -ForbiddenOu to skip OUs such as service accounts or admin-only accounts during AD matching.
• Save ownership-import.definition.json and ownership-import-rerun.ps1 so the import can be repeated without rerunning the whole interview.
• Pass the enriched file to scans with -OwnershipEnrichmentPath; the scan exports it as ownership_enrichment.csv.
• Pass context graph files to scans with -OwnershipContextPath, -OwnershipRelationshipPath, and -OwnershipImportManifestPath when you want the export/dashboard to show project-to-OBS or path/group context evidence.
• If owners are not known yet, create owner-mapping-draft.csv and owner-mapping-rerun.ps1 with New-ShareSurferOwnerMappingDraft.
• Before scanning with a hand-edited owner-mapping.csv, run Test-ShareSurferOwnerMapping so missing columns, blank owners, and risky sibling-prefix patterns are caught early.

Nonpermissive / Two-Host Operation

Many environments intentionally block internet access, npm, browser tooling, or WinRM/CIM on the collector. That is fine. Keep the roles simple:

• Collector host: runs Invoke-ShareSurferScan, reads SMB/share/ACL/owner/inheritance data, enriches identities, and writes the export.
• Validation step: runs Test-ShareSurferExport and reviews partial-data warnings.
• Dashboard host: opens report.html, a packaged standalone dashboard, or the optional native viewer from the transferred export.
• Support path: use New-ShareSurferSupportBundle when anything leaves trusted handling.

See the nonpermissive collector to dashboard host workflow for the full walkthrough. For very large exports where browser-based review becomes the bottleneck, see the optional native viewer.

Quick Start in a Nonpermissive Environment

Use this compact pattern when the release folder has been copied to a locked-down Windows collector host:

$shareSurferRoot = 'C:\ShareSurfer-0.1.0-pre.43'
$exportPath = 'C:\ShareSurfer\exports\scan-001'
$handoffPath = 'C:\ShareSurfer\handoff\scan-001.zip'
$inputRoot = 'C:\ShareSurfer\inputs'
$ownerMappingPath = Join-Path $inputRoot 'owner-mapping.csv'
$ownershipSourcePath = Join-Path $inputRoot 'hr-obs.csv'
$ownershipEnrichmentPath = Join-Path $inputRoot 'ownership-enrichment.csv'
$discountedPrincipalPath = Join-Path $inputRoot 'discounted-principals.csv'

Get-ChildItem -LiteralPath $shareSurferRoot -Recurse -File |
  Where-Object { $_.Extension -in '.ps1', '.psm1', '.psd1' } |
  Unblock-File
Import-Module "$shareSurferRoot\src\ShareSurfer\ShareSurfer.psd1" -Force

if (Test-Path -LiteralPath $ownershipSourcePath) {
  Join-ShareSurferOwnershipSources `
    -Path $ownershipSourcePath `
    -OutputPath $ownershipEnrichmentPath `
    -DefinitionPath (Join-Path $inputRoot 'ownership-import.definition.json') `
    -ObsAttribute 'extensionAttribute10' `
    -AdLookupMode Auto `
    -ForbiddenOu @('OU=Service Accounts,DC=contoso,DC=com') `
    -ReusableCommandPath (Join-Path $inputRoot 'ownership-import-rerun.ps1') `
    -Force
}

$scanParams = @{
  TargetPath = '\\files01\Finance'
  OutputPath = $exportPath
  ObsAttribute = 'extensionAttribute10'
  ManagerIdentityFormat = 'MailTo'
  AdLookupMode = 'Auto'
}
if (Test-Path -LiteralPath $ownerMappingPath) { $scanParams.OwnerMappingPath = $ownerMappingPath }
if (Test-Path -LiteralPath $ownershipEnrichmentPath) { $scanParams.OwnershipEnrichmentPath = $ownershipEnrichmentPath }
if (Test-Path -LiteralPath $discountedPrincipalPath) { $scanParams.DiscountedPrincipalPath = $discountedPrincipalPath }

Invoke-ShareSurferScan @scanParams
Test-ShareSurferExport -ExportPath $exportPath

$handoffFolder = Split-Path -Parent $handoffPath
if (-not (Test-Path -LiteralPath $handoffFolder)) {
  Write-Host "Creating missing local handoff folder: $handoffFolder"
  New-Item -ItemType Directory -Force -Path $handoffFolder | Out-Null
}
Compress-Archive -Path "$exportPath\*" -DestinationPath $handoffPath -Force
Get-FileHash -Algorithm SHA256 -Path $handoffPath

The recommended first-scan preset does not require ownership files. Use Add ownership or HR data from the home screen, or Customize technical settings during setup, when those files are available. ShareSurfer uses recognized files under the input folder and skips missing optional inputs. After a validated first scan, it can create owner-mapping-draft.csv for completion before owner review. Startup-generated rerun scripts also write port_protocol_*.csv readiness evidence into the export folder before packaging the standalone dashboard.

The Unblock-File line is repeated here on purpose. It avoids one-file-at-a-time prompts after ZIP transfer. If the launcher is run before this manual unblock, Windows may still ask once for Start-ShareSurfer.ps1 before ShareSurfer can clear the rest of the folder. ShareSurfer commands create missing local output folders by default and can opt out with -NoCreateMissingFolders; the handoff ZIP uses native PowerShell, so the snippet creates that local folder explicitly before Compress-Archive. Move the handoff ZIP and hash by your approved transfer process, then package or open the dashboard on the review host.

SMB/RPC Fallback Notes

When WinRM/CIM is blocked, scan explicit SMB shares with the native provider:

Invoke-ShareSurferScan -ComputerName 'files01' -ShareName 'Finance' -SmbCollectionProvider NativeSmbRpc -OutputPath $exportPath

NativeSmbRpc uses Windows SMB/RPC and Win32 security APIs instead of Get-SmbShare, Get-SmbShareAccess, or Get-Acl. It is still permission-dependent. If SMB/RPC ports pass but ShareSurfer reports unavailable or unparseable security descriptors, treat the scan as reachable but incomplete until permissions or SMB server behavior are reviewed. For older SAN or appliance shares that return a server-local path such as C:\Public\Share, ShareSurfer diagnostics now verify whether that path is collector-local and fall back to the target UNC path when needed. Target-path scans such as \\files01\Finance also try native SMB/RPC share-permission evidence when Get-SmbShareAccess cannot return rows.

Standalone Dashboard

Release packages include built dashboard assets at interface/standalone-dashboard/dist. Release users can package and open dashboard output from index.html without npm, Vite, a development server, or internet access.

The release assets are templates. Opening interface\standalone-dashboard\dist\index.html directly shows a template/onboarding screen. For real review, package a validated export:

powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "$releaseRoot\scripts\New-ShareSurferStandaloneDashboard.ps1" `
  -ExportPath $exportPath `
  -OutputPath "$exportPath\standalone-dashboard" `
  -Force
Start-Process "$exportPath\standalone-dashboard\index.html"

Developers can still use npm --prefix interface/standalone-dashboard run dev, npm --prefix interface/standalone-dashboard run build, and pwsh -NoLogo -NoProfile -File scripts/New-ShareSurferStandaloneDashboard.ps1.

Current screenshots are under docs/visuals/dashboard-screenshots/2026-06-09-current. A future signed Windows viewer is sketched in docs/webview2-dashboard-viewer.md.

Pre-1.0 Release Packaging

The first packages are unsigned but fully built. v0.1.0-pre.43 includes the module, scripts, docs, SHA256 files, release manifest, dependency-age report, and prebuilt dashboard template assets. The manifest records UnsignedPre1.0.

Release identity lives in release-metadata.json. Update that file first when preparing a prerelease; packaging fails closed when the manual version or tag does not match.

Build a local unsigned package:

pwsh -NoLogo -NoProfile -File scripts/New-ShareSurferRelease.ps1 -OutputRoot .\artifacts -Force

Output lands in artifacts\ShareSurfer-<version>\, artifacts\ShareSurfer-<version>.zip, and artifacts\ShareSurfer-<version>.zip.sha256.

Lab Fixture

Plan first:

New-ShareSurferLabFixture -OutputPlanOnly -RootPath 'C:\ShareSurferLab' -DomainNetBiosName 'CONTOSO' -ObsAttribute 'extensionAttribute10'

Enterprise validation should use the scaled profile and live evidence gate:

New-ShareSurferLabFixture -OutputPlanOnly -RootPath 'C:\ShareSurferEnterpriseLab' -Scale Enterprise -EnterpriseUserCount 2500 -EnterpriseShareCount 250 -EnterpriseFilesPerShare 8

For live validation, see operator workflow, scaled lab generator spec, Windows lab readiness checklist, and PowerShell testing and lab verification.

Azure Files Path Policy

Microsoft documents 255-character path components and 2,048-character full paths for Azure Files. ShareSurfer defaults to flagging full paths over 256 characters as an operational migration warning, not as proof that Azure Files cannot store the path. See Azure Files path policy.

Documentation

• First-run guide
• Command recipes
• Glossary
• First-run troubleshooting
• Business review handoff
• Nonpermissive collector to dashboard host workflow
• Operator workflow
• PowerShell testing and lab verification
• Management overview and offline slide
• Visual field guide
• Workflow guide
• Export schema
• Redacted support bundles
• Standalone dashboard interface spec
• WebView2 dashboard viewer concept
• V1 phase-1 acceptance audit
• Workflow visuals

Tests

Dependency-free suite:

pwsh -NoLogo -NoProfile -File tests/Invoke-ShareSurferTests.ps1

Optional Pester wrapper:

pwsh -NoLogo -NoProfile -File scripts/Invoke-ShareSurferPester.ps1