AD2004: EnableSecureSourceCodeHashing¶

Summary¶

Description¶

Compilers can optionally generate checksums (hashes) of source files when emitting debug information. These checksums help verify that a binary was built from the source code it claims. The /ZH:SHA_256 flag instructs the compiler to use SHA-256 for source file hashing.

Insecure algorithms like MD5 or SHA-1 are considered deprecated for security purposes and should not be used.

How It Works¶

The rule examines the PDB file associated with a binary and checks the hash algorithm used for source file checksums. Modern versions of MSVC support:

• MD5 - Deprecated, vulnerable to collision attacks
• SHA-1 - Deprecated, practical collision attacks exist
• SHA-256 - Recommended, cryptographically secure

Why This Matters¶

Debug information in PDB files can include checksums of the original source files used during compilation. These checksums serve as a cryptographic link between binaries and their source code, enabling verification that a binary was built from the expected source.

The Cryptographic Problem¶

Not all hash algorithms provide equal security:

With MD5 or SHA-1, an attacker could potentially create a malicious source file with the same hash as the legitimate file, allowing supply chain attacks that pass source verification.

Supply Chain Security¶

Source file hashing supports several security scenarios:

1. Build Verification: Confirm that a binary was built from audited source code by checking if the source file hashes in the PDB match the expected values.

2. Incident Response: When investigating a security incident, verify that production binaries match the source code in your repository.

3. Reproducible Builds: As part of a reproducible build system, source hashes help verify that the correct inputs produced the expected output.

4. Tampering Detection: If source files are modified after a build (to hide evidence of insertion), the hash mismatch reveals the tampering.

Real-World Impact¶

The SolarWinds attack (2020) demonstrated how attackers can inject malicious code into build systems. While source hashing alone wouldn't prevent such attacks, it provides one verification layer that could help detect unauthorized modifications when combined with other controls.

Performance and Compatibility¶

Using SHA-256 instead of MD5 for source hashing has no impact on runtime performance—the hashing only occurs during compilation. The only consideration is that Visual Studio 2019 version 16.4 or later is required.

Resolution¶

For Visual Studio / MSVC¶

Add the /ZH:SHA_256 compiler flag:

cl.exe /ZH:SHA_256 ...

Or in project properties: 1. Open Project Properties 2. Navigate to C/C++ → Command Line 3. Add /ZH:SHA_256 to Additional Options

For MSBuild¶

<PropertyGroup>
  <AdditionalOptions>/ZH:SHA_256 %(AdditionalOptions)</AdditionalOptions>
</PropertyGroup>

For CMake¶

if(MSVC)
    add_compile_options(/ZH:SHA_256)
endif()

When to Suppress¶

This rule can be suppressed in the following scenarios:

• Non-MSVC toolchains: This rule only applies to binaries compiled with MSVC. Binaries compiled with Rust, GCC, Clang, or other compilers use different debug formats (typically DWARF) and do not support the /ZH:SHA_256 flag. The rule automatically skips these binaries.
• Older toolchains: Visual Studio versions before VS 2019 16.4 don't support /ZH:SHA_256
• No PDB required: Release builds that won't ship PDB files
• Third-party code: When you can't control the build process

Caveats¶

• Requires Visual Studio 2019 version 16.4 or later
• Only applies when generating PDB debug information
• Does not affect the security of the binary itself, only debug info

Related Rules¶

• AD2006: BuildWithSecureTools
• AD2027: EnableSourceLink

References¶

• /ZH (Hash Algorithm for Checksums)
• Visual Studio 2019 Release Notes