AD2027: EnableSourceLink¶

Summary¶

Description¶

Binaries should include SourceLink information in their PDB files. SourceLink enables debuggers to automatically download matching source code from source control, improving the debugging and incident response experience for both developers and security researchers.

How It Works¶

The rule examines PDB files for the presence of SourceLink JSON data. This data maps local file paths to source control URLs, allowing debuggers to fetch the exact source version.

Why This Matters¶

SourceLink bridges the gap between compiled binaries and their source code, enabling precise debugging and security analysis. When a security incident occurs, SourceLink can mean the difference between hours of investigation and immediate root cause analysis.

The Debugging Problem¶

Without SourceLink, debugging production crashes is painful:

1. Get crash dump with stack trace
2. Which version of the code is this?
3. Hunt through source control history
4. Manually match commit to binary version
5. Checkout correct version
6. Finally, examine the code

Time: Hours to days

With SourceLink:

1. Get crash dump with stack trace
2. Open in debugger
3. Source automatically downloaded from correct commit
4. Immediate investigation

Time: Minutes

Security Investigation Value¶

SourceLink accelerates security response:

Supply Chain Security¶

SourceLink contributes to supply chain verification:

1. Provenance: Links binary to specific source control commit
2. Reproducibility: Supports reproducible build verification
3. Audit trail: Documents exactly what code was compiled
4. Integrity: Source URLs in PDB provide verification path

How SourceLink Works¶

// SourceLink JSON in PDB
{
  "documents": {
    "C:\\src\\*": "https://raw.githubusercontent.com/org/repo/commit/*"
  }
}

The debugger: 1. Reads local path from PDB 2. Maps through SourceLink rules 3. Fetches source from URL 4. Displays in debugger

NuGet Package Best Practice¶

For published packages, SourceLink is essential:

Security Considerations¶

SourceLink URLs should point to authenticated, versioned sources:

Privacy Considerations¶

SourceLink URLs are embedded in PDBs:

• Public packages: Source URLs are intentionally public
• Private software: Ensure URLs don't leak internal infrastructure
• Sensitive code: Consider if source URL exposure is acceptable

For private code, strip SourceLink data from publicly distributed PDBs.

Resolution¶

Enable SourceLink¶

Install the SourceLink NuGet package for your source control:

GitHub:

<PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1" PrivateAssets="All" />

Azure DevOps:

<PackageReference Include="Microsoft.SourceLink.AzureRepos.Git" Version="1.1.1" PrivateAssets="All" />

GitLab:

<PackageReference Include="Microsoft.SourceLink.GitLab" Version="1.1.1" PrivateAssets="All" />

MSBuild Properties¶

Enable SourceLink in your project:

<PropertyGroup>
  <PublishRepositoryUrl>true</PublishRepositoryUrl>
  <EmbedUntrackedSources>true</EmbedUntrackedSources>
  <IncludeSymbols>true</IncludeSymbols>
  <SymbolPackageFormat>snupkg</SymbolPackageFormat>
</PropertyGroup>

CMake¶

For CMake projects, use a post-build step or custom tooling to inject SourceLink data.

When to Suppress¶

This rule may be suppressed for:

• Private/internal code: When source shouldn't be externally accessible
• Security concerns: When exposing source URLs is problematic
• No source control: Projects not using Git
• Build system limitations: When SourceLink can't be integrated

Caveats¶

• Source must be accessible from where debugging occurs
• Private repos need authentication configured
• Only works with supported source control providers
• Requires proper CI/CD configuration

SourceLink Providers¶

Verifying SourceLink¶

Check if SourceLink is embedded:

# Using sourcelink tool
dotnet tool install -g sourcelink
sourcelink print-urls MyAssembly.pdb

Related Rules¶

• AD2004: EnableSecureSourceCodeHashing

References¶

• SourceLink
• Source Link documentation