Edit

Share via

Test-FileCatalog

  • Reference
Module:
Microsoft.PowerShell.Security

Test-FileCatalog validates whether the hashes contained in a catalog file (.cat) matches the hashes of the actual files in order to validate their authenticity.

This cmdlet is only supported on Windows.

Syntax

Test-FileCatalog
    [-Detailed]
    [-FilesToSkip <String[]>]
    [-CatalogFilePath] <String>
    [[-Path] <String[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

This cmdlet is only available on the Windows platform.

Test-FileCatalog validates the authenticity of files by comparing the file hashes of a catalog file (.cat) with the hashes of actual files on disk. If it detects any mismatches, it returns the status as ValidationFailed. Users can retrieve all this information by using the -Detailed parameter. It also displays signing status of catalog in Signature property, which is equivalent to calling Get-AuthenticodeSignature cmdlet on the catalog file. Users can also skip any file during validation by using the -FilesToSkip parameter.

This cmdlet is only supported on Windows.

Examples

Example 1: Create and validate a file catalog

$NewFileCatalogParams = @{
    Path = "$PSHOME\Modules\Microsoft.PowerShell.Utility"
    CatalogFilePath = "\temp\Microsoft.PowerShell.Utility.cat"
    CatalogVersion = 2.0
}
New-FileCatalog @NewFileCatalogParams

$TestFileCatalogParams = @{
    CatalogFilePath = "\temp\Microsoft.PowerShell.Utility.cat"
    Path = "$PSHOME\Modules\Microsoft.PowerShell.Utility\"
}
Test-FileCatalog @TestFileCatalogParams

Valid

Example 2: Validate a file catalog with detailed output

$TestFileCatalogParams = @{
    Detailed = $true
    CatalogFilePath = "\temp\Microsoft.PowerShell.Utility.cat"
    Path = "$PSHOME\Modules\Microsoft.PowerShell.Utility\"
}
Test-FileCatalog @TestFileCatalogParams

Status        : Valid
HashAlgorithm : SHA256
CatalogItems  : {[Microsoft.PowerShell.Utility.psd1,
                A7028BD54018AE519381CDF5BF91F3B0417BD9345478086089ACBFAD05C899FC], [Microsoft.PowerShell.Utility.psm1,
                1127E8151FB86BCB683F932E8F6538552F7195816ED351A28AE07A753B8F20DE]}
PathItems     : {[Microsoft.PowerShell.Utility.psd1,
                A7028BD54018AE519381CDF5BF91F3B0417BD9345478086089ACBFAD05C899FC], [Microsoft.PowerShell.Utility.psm1,
                1127E8151FB86BCB683F932E8F6538552F7195816ED351A28AE07A753B8F20DE]}
Signature     : System.Management.Automation.Signature

Parameters

-CatalogFilePath

A path to a catalog file (.cat) that contains the hashes to be used for validation.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Detailed

Returns more information a more detailed CatalogInformation object that contains the files tested, their expected/actual hashes, and an Authenticode signature of the catalog file if it's signed.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-FilesToSkip

An array of paths that should not be tested as part of the validation.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Path

A folder or array of files that should be validated against the catalog file.

Type:String[]
Position:1
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Inputs

DirectoryInfo

You can pipe a DirectoryInfo object representing the path to the files that need to be validated.

String

You can pipe a string representing the path to the files that need to be validated.

Outputs

CatalogValidationStatus

By default, this cmdlet returns a CatalogValidationStatus object with a value of either Valid or ValidationFailed.

CatalogInformation

When you use the Detailed parameter, the cmdlet returns a CatalogInformation object for each file, which can be used to analyze specific files that may or may not have passed validation, which hashes were expected vs. found, and the algorithm used in the catalog.

Notes

This cmdlet is only available on Windows platforms.