FileHasher

A utility to hash files and folders, write sidecar hash files, and export results to CSV. The original implementation is a PowerShell script; the compiled Windows GUI application started from that script's design but has been iterated on extensively since and now offers significantly more functionality than the script.

• Windows GUI Application
  • Requirements
  • Building
  • Reproducible builds
  • Usage
    • Selecting a target
    • Choosing a hash algorithm
    • Options
    • Running and stopping
    • Results
    • Logs
    • UAC elevation
    • About dialog
• Automated Testing
  • Test project overview
  • Running the tests
  • AutomationId reference
  • Test classes
  • CI / custom exe path
• PowerShell Script
  • Parameters
  • Examples
• Acknowledgements

A self-contained, portable 64-bit Windows executable built on .NET 8 and WinForms. No installer or runtime dependency required.

• Windows 10 or Windows 11 (64-bit)
• .NET 8 SDK — only needed to build; the published .exe is fully self-contained

From a Windows machine with the .NET 8 SDK installed, open a terminal in the FileHasherApp folder and run:

# Self-contained single-file executable (recommended)
dotnet publish -c Release -r win-x64 `
    --self-contained true `
    -p:PublishSingleFile=true `
    -p:EnableCompressionInSingleFile=true `
    -p:DebugType=embedded

Output: bin\Release\net8.0-windows\win-x64\publish\FileHasher.exe

Copy FileHasher.exe anywhere you like — it has no external dependencies.

This section is for anyone who wants to independently verify that the published binaries match the source in this repository — useful for security review, downstream packaging, or peace of mind.

The CI pipeline passes -p:Deterministic=true -p:ContinuousIntegrationBuild=true to dotnet publish so the unsigned executable content can be reproduced byte-for-byte from a clean checkout with matching tools. The trailing Authenticode signature on the released .exe is appended by the maintainer's code-signing step using a hardware token, so the signed region of the file will always differ between a third-party rebuild and an official release; what you can verify byte-for-byte is the underlying executable.

1. Check out the tag you want to verify:

   git fetch --tags
   git checkout vX.Y.Z

2. Install the .NET SDK version pinned by the repo's global.json at the root, for example:

   {
     "sdk": {
       "version": "8.0.420",
       "rollForward": "disable"
     }
   }

   rollForward: "disable" means dotnet will refuse to build if that exact patch isn't installed, so you can't accidentally use a different SDK. Each release tag carries the global.json content the CI used at that time; checking out the tag and installing the SDK it names is all the version-matching you need.
3. Build from FileHasherApp\:

   dotnet publish -c Release -r win-x64 `
       --self-contained true `
       -p:PublishSingleFile=true `
       -p:EnableCompressionInSingleFile=true `
       -p:DebugType=embedded `
       -p:Version=X.Y.Z `
       -p:Deterministic=true `
       -p:ContinuousIntegrationBuild=true

   The two flags beyond the regular Building command are what make the output stable across machines:
   • Deterministic=true — replaces build timestamps and random GUIDs in PE/PDB metadata with content-derived values.
   • ContinuousIntegrationBuild=true — normalizes embedded source paths so the PDB content doesn't depend on your build machine's directory layout.
4. The output at FileHasherApp\bin\Release\net8.0-windows\win-x64\publish\FileHasher.exe should be byte-identical to:
   • the unsigned FileHasher.exe artifact uploaded by the CI's build stage (available on the pipeline's job page for 30 days after the release), or
   • the signed release .exe with its trailing Authenticode certificate table stripped — for example via osslsigncode remove-signature signed.exe unsigned.exe.

Compare with any SHA-256 utility. A match means the published bytes came from this source at that tag.

• Match the SDK first. Patch-level SDK drift is the single biggest source of size and byte differences; even one patch apart will diverge by tens or hundreds of KB after compression. The SDK version the CI used to produce a given release is recorded in that pipeline's build job log.
• Applies only to releases built after the CI adopted deterministic flags. Binaries from tags cut before .gitlab-ci.yml started passing -p:Deterministic=true -p:ContinuousIntegrationBuild=true (initial release v0.1.1 predates the change) cannot be reproduced byte-for-byte regardless of the local flags used.
• The signature itself can't be reproduced without access to the same code-signing certificate and HSM token. Verification of the signature, separate from binary reproduction, is done with standard tools like signtool verify or osslsigncode verify against the signed release .exe.

You can also type or paste a path directly into the path box, or drag and drop a file or folder onto it. Dropping a folder automatically enables the Scan all file types checkbox; dropping a file disables it (matching the Browse buttons' behaviour).

Scan all file types — when scanning a folder, this checkbox controls which files are included:

• Unchecked (default) — only .exe and .msi files are hashed, matching the behaviour of the PowerShell script.
• Checked — every file in the folder tree is hashed.

This option is not applicable when a single file is selected.

Select one of the four algorithms using the radio buttons in the Hash Algorithm group. SHA256 is selected by default.

The column header in the results list and the CSV export header update automatically to reflect the selected algorithm.

Include file metadata When checked, two additional columns are populated in the results list and CSV export: Size (bytes) and Modified (UTC).

Write sidecar hash files Writes a small text file next to each hashed file. For example, hashing setup.exe produces setup.exe.sha256 alongside it.

• Extension — the suffix appended to the original filename. The suggested value follows the selected hash algorithm automatically (.md5, .sha1, .sha256, .sha512); switching algorithms updates the box only while it still holds one of those four standard values, so a custom extension you typed is never overwritten.
• Format — controls the content of the sidecar file:
  • {algo}sum format (default) — HASH *filename, compatible with the standard md5sum/sha1sum/sha256sum/sha512sum tools. The radio button's label follows the selected algorithm (e.g. sha256sum format when SHA256 is selected).
  • Hash only — the raw hash string with no filename, useful for simple verification scripts.
  • Extended — HASH *filename *lastModified *sizeBytes, where the last-modified timestamp is ISO-8601 UTC (e.g. 2026-08-09T14:33:05Z), matching the CSV export's LastWriteUtc format.

Writing sidecars to protected locations (e.g. C:\Program Files) requires Administrator rights — see UAC elevation.

When a sidecar file already exists for a target file, FileHasher pauses before hashing begins and shows a per-file conflict dialog. The dialog displays:

• File — full path of the source file
• Size — file size in bytes
• Modified — last-modified timestamp (UTC)
• Existing sidecar — name of the sidecar that is already on disk
• Sidecar written — timestamp when the existing sidecar was last written

Four buttons let you choose what to do:

All conflict decisions are collected before any file is hashed, so no file is touched until every dialog has been answered.

The completion summary (see Running and stopping) includes Sidecars skipped and Sidecars overwritten counts when at least one conflict was resolved.

Sidecar files are never themselves treated as hash targets — FileHasher automatically excludes any file whose path ends with the configured sidecar extension, preventing .sha256.sha256 chains on repeated runs.

Export results to CSV When checked, a CSV file is written after all files have been hashed. Click Browse… to choose the output path, or type one directly.

• Encoding: UTF-8 with BOM (opens correctly in Microsoft Excel without an import wizard).
• Only successfully hashed files are included; errors are omitted.
• Rows are sorted by file path.
• Columns: Path, <Algorithm>, and (if metadata is enabled) LengthBytes, LastWriteUtc.

Hash files inside MSI installers (experimental) When checked, every .msi file the worker encounters is also opened read-only via the Windows Installer database API, and the files contained inside it are hashed individually in addition to the MSI itself. Each inner file appears as its own results row prefixed with [parent.msi], colored steel-blue, with the MSI's internal install path (e.g. Program Files\msi-test\foo.exe) in the File Path column and the raw MSI Directory-table identifier (e.g. PFiles64, INSTALLDIR) in a new MSI Dir column on the right. The CSV export gains optional Container and MsiDirectoryId columns when this option is on.

The Scan all file types checkbox above also drives the inner-MSI filter: when unchecked, only .exe and .msi inner files are surfaced; when checked, every inner file regardless of extension. The checkbox stays enabled whenever the target is a folder OR an .msi file with this option on.

The MSI is treated as data — the database is opened read-only and the contents extracted to a sandboxed per-MSI temp directory that's deleted as soon as hashing finishes. The installer is not executed.

For the full security model (file-size / total-size / file-count / disk-headroom caps, path-traversal and reparse-point rejection, sibling-escape cleanup), the test-coverage layout across all three tiers, and the known limitations, see README-msi-inner-scan.md.

The progress bar shows indeterminate (marquee) progress during folder enumeration, then switches to a percentage bar during hashing. When hashing completes successfully the bar turns blue.

A completion dialog is shown at the end of every run summarising:

• Files hashed — count of successfully hashed files
• Errors — count of files that failed
• Sidecars skipped — shown only when at least one existing sidecar was left in place
• Sidecars overwritten — shown only when at least one existing sidecar was replaced
• Log — path to the current log file

Verify Sidecars re-hashes files and compares the result against their existing sidecar files, using the current Target path and the Extension configured under the sidecar options (the Write sidecar hash files checkbox does not need to be checked). For a folder target the scan is recursive; targeting a single file verifies that file's sidecar, and targeting a sidecar file directly verifies it against its base file.

The hash algorithm is auto-detected per sidecar from the length of the stored hash (32 hex characters = MD5, 40 = SHA1, 64 = SHA256, 128 = SHA512), so the algorithm radio selection is ignored during verification and a folder with mixed-algorithm sidecars verifies correctly in one pass. All three sidecar formats are recognized: bare hash, HASH *filename, and the extended HASH *filename *lastModified *sizeBytes.

Each verified item appears as one results row (the hash column header becomes Verification):

The hash alone decides pass/fail. For extended-format sidecars, a differing embedded filename, modified date, or size on an otherwise-matching row is appended as an informational note — a file's modified date often changes legitimately on copy or restore.

Verification runs are logged like hashing runs and end with the same style of summary dialog (per-verdict counts). The Export results to CSV option does not apply to verification runs.

The results list shows one row per file:

Warnings (e.g. inaccessible subdirectories) appear as orange rows.

Right-clicking a result row opens a context menu:

• Open in File Explorer — opens the containing folder with the file pre-selected (explorer /select). If the file has been deleted since it was hashed, the folder is opened plainly instead.
• Open PowerShell here — opens a Windows PowerShell window in the containing folder.
• Open Command Prompt here — opens a cmd window in the containing folder.
• Copy Hash — copies the row's hash to the clipboard (disabled on error rows and on verification rows where no hash was computed).
• Copy File Path — copies the row's full on-disk path to the clipboard.

Double-clicking a row (or pressing Enter on it) performs the Explorer action directly.

For inner-MSI rows (experimental MSI scan), the location-based actions target the containing .msi file — the extracted temp copies are already deleted by the time results are browsable — and Copy File Path copies that .msi path. Warning rows have no payload, so no menu appears for them. The three Open items are greyed out when the row's folder no longer exists; the copy items keep working.

Every run is automatically logged. Log files are written to:

%APPDATA%\FileHasher\Logs\FileHasher_YYYY-MM-DD.log

Each log entry records the timestamp (UTC), algorithm, result (OK or ERROR), hash, file path, and (when metadata is enabled) file size and last modified date. A session header and footer are written at the start and end of each run.

Click the path shown in the status bar at the bottom of the window to open the log folder in Explorer.

FileHasher starts as a standard user by default. Elevation is needed in two situations:

• Reading files in protected locations (e.g. C:\Windows\System32).
• Writing sidecar files next to installers in protected locations (e.g. C:\Program Files).

To elevate:

• Click Run as Administrator… before starting a run. The application will prompt for UAC confirmation and relaunch with Administrator privileges. The title bar and status bar will confirm elevated status.
• If a run encounters an access-denied error mid-way, a dialog will offer to relaunch as Administrator automatically.

When already running as Administrator, the button is disabled and the status bar shows ● Administrator.

Open Help → About FileHasher… from the menu bar to view the application version, author, and copyright information.

FileHasher's GUI is covered by a UI automation test suite built on FlaUI and xUnit. The tests launch the real FileHasher.exe, interact with it through the Windows UI Automation (UIA3) accessibility tree, and assert on observable behaviour — no mocking.

Key packages:

<PackageReference Include="FlaUI.Core"                Version="4.0.0" />
<PackageReference Include="FlaUI.UIA3"                Version="4.0.0" />
<PackageReference Include="xunit"                     Version="2.8.1" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.8.1" />

Build FileHasherApp first (the tests locate the compiled executable automatically):

# From the solution root
dotnet build FileHasherApp\FileHasherApp.csproj -c Debug

dotnet test FileHasherApp.Tests\FileHasherApp.Tests.csproj

All tests run serially (via xUnit's [Collection("Serial")]) because they interact with real application windows on the Windows desktop.

Every interactive control in MainForm.cs is assigned a Name property, which WinForms surfaces as the UIAutomation AutomationId. FlaUI locates controls with:

window.FindFirstDescendant(cf => cf.ByAutomationId("RunBtn")).AsButton()

MainFormStateTests — read-only assertions about the form's initial state. All tests share one app instance (IClassFixture<AppFixture>) so none of them modify UI state.

MainFormInteractionTests — basic interaction tests. Each test gets its own app process.

MainFormAlgorithmTests — algorithm selection completeness and hash-value accuracy. Hash output is verified by writing a sidecar in hash-only format and comparing it against the .NET HashAlgorithm provider for the same bytes.

MainFormFolderTests — folder scanning, file filters, recursive subdirectories, and the Stop button.

MainFormSidecarTests — sidecar file creation, content formats, custom extensions, and the full conflict-resolution dialog.

MainFormCsvTests — CSV export file creation, content verification, metadata columns, and missing-path validation.

MainFormEdgeCaseTests — edge cases, error paths, and miscellaneous UI invariants.

MainFormSidecarAlgoUiTests — the sidecar suggested extension and the {algo}sum format radio label follow the selected hash algorithm. Each test gets its own app process.

MainFormContextMenuTests — the right-click context menu on result rows and double-click activation. The three Open items are deliberately never invoked (they would spawn real Explorer/PowerShell/cmd processes on the test host); their presence and enabled state are asserted instead. Each test gets its own app process.

MainFormVerifyTests — end-to-end tests for the Verify Sidecars button through the UI: button flow, completion dialog, status-line counts, and row counts. Verdict-level precision lives in SidecarVerifierTests. Each test gets its own app process.

SidecarVerifierTests — direct unit tests against the internal SidecarVerifier class (via InternalsVisibleTo, no UI, parallelizable): sidecar parsing across all three formats, hash-length algorithm auto-detection, status classification, informational metadata notes, and folder enumeration/filtering.

AppFixture locates the executable by walking up from the test assembly's output directory, trying Debug then Release configurations. To override this (e.g. in a CI pipeline that publishes to a specific location), set the FILEHASHER_EXE environment variable to the full path of FileHasher.exe:

$env:FILEHASHER_EXE = "C:\build\output\FileHasher.exe"
dotnet test FileHasherApp.Tests\FileHasherApp.Tests.csproj

filehasher.ps1 is the original script that the GUI application is based on. It recursively scans a folder for .exe and .msi files, computes SHA256 hashes, and optionally writes sidecar files and a CSV report.

# Hash all .exe and .msi files under C:\Installers, print to console
.\filehasher.ps1 -RootPath "C:\Installers"

# Include metadata and export to CSV
.\filehasher.ps1 -RootPath "C:\Installers" -IncludeMetadata -OutCsv "C:\hashes.csv"

# Write sha256sum-compatible sidecar files next to each installer
.\filehasher.ps1 -RootPath "C:\Installers" -WriteSidecarHashes

# Write hash-only sidecar files with a custom extension
.\filehasher.ps1 -RootPath "C:\Installers" -WriteSidecarHashes -SidecarExtension ".hash" -SidecarFormat hashonly

This project was developed with assistance from Anthropic's Claude AI. Per-commit attribution is recorded in the git history via Co-Authored-By lines.