Exploring the PowerShell Cmdlet: New-FileCatalog

Welcome back to Wahmans Powershell Blog! Today we’re exploring a lesser-known but powerful cmdlet: New-FileCatalog. This cmdlet is used to create a Windows catalog file that contains cryptographic hashes of files and folders from specified paths. These catalog files can be extremely useful for verifying file integrity, securing software distribution, and compliance auditing.

What does New-FileCatalog do?

When you run New-FileCatalog, PowerShell creates a .cat (catalog) file. This file doesn’t contain the actual data, but hashes for integrity verification. It’s often used in deployment, security, and software packaging procedures. You can also use it with the Test-FileCatalog cmdlet to validate that files haven’t changed over time.

---

Let’s dive into some examples

1. Basic Usage – Hashing a Folder

This is a great starting point. Let’s catalog a simple directory of scripts.

New-FileCatalog -Path "C:\Scripts" -CatalogFilePath "C:\Catalogs\ScriptCatalog.cat" -CatalogVersion 2.0

This command creates a catalog file from all files in C:\Scripts, saving the catalog to C:\Catalogs\ScriptCatalog.cat.

2. Catalog a Specific File

Sometimes you only need to catalog one file. Here’s how:

New-FileCatalog -Path "C:\Deployments\installer.exe" -CatalogFilePath "C:\Catalogs\InstallerCatalog.cat" -CatalogVersion 2.0

You can then use this catalog to verify the file later, ensuring it hasn’t been tampered with post-distribution.

3. Use With Test-FileCatalog

Here’s how to make sure files haven’t been altered over time:

# Generate the catalog
New-FileCatalog -Path "C:\Projects\Build-1" -CatalogFilePath "C:\Catalogs\Build1.cat" -CatalogVersion 2.0

# Later, validate
Test-FileCatalog -Path "C:\Projects\Build-1" -CatalogFilePath "C:\Catalogs\Build1.cat"

This can be especially helpful for ensuring build integrity in CI/CD pipelines or software logs.

4. Automating Catalog Creation for CI/CD

Let’s say you want to automatically create a catalog file post-build in your CI/CD pipeline (for example, with Azure DevOps or GitHub Actions). Here’s a script snippet:

$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
$outputCatalog = "C:\BuildOutput\Catalogs\Release_$timestamp.cat"
New-FileCatalog -Path "C:\BuildOutput\Release" -CatalogFilePath $outputCatalog -CatalogVersion 2.0
Write-Output "Catalog created: $outputCatalog"

This approach allows you to timestamp and archive catalog files for every release build, improving auditing and traceability.

---

Wrap Up

Using New-FileCatalog is a fantastic way to bring integrity and security to your PowerShell and deployment workflows. Whether you’re a beginner cataloging your scripts or a seasoned pro maintaining chain-of-custody logs for build assets, this cmdlet is a solid addition to your toolset.

Happy scripting, and I will see you in the next post!