Tracking Upstream Patch Provenance in Vendored Git Trees

In‑tree cherry‑picks erase their source

A developer copies an upstream fix into a vendored subtree and commits it as a plain patch. Weeks later the commit message is edited, the branch is rebased, or the file is moved. The original upstream SHA‑1 disappears. When a licence audit or a security advisory asks “which upstream version introduced this line?”, the repository cannot answer. The missing link becomes a liability: you cannot prove that the code is covered by a permissive licence, nor can you locate the upstream patch that fixes a vulnerability.

Relying on ad‑hoc comments is fragile

Teams often add a comment at the top of the file:

// cherry‑picked from upstream@a1b2c3 – MIT

That line is easy to delete, to rewrite, or to forget when the file is reformatted. It does not survive a git filter‑branch, a subtree split, or a merge that resolves conflicts automatically. Moreover, the comment does not give a machine‑readable way to verify the claim, so an SBOM generator cannot include the upstream reference without custom scripting.

Store a cryptographic reference next to the vendored file

Treat the provenance record as a first‑class artifact. For each vendored file create a sibling file with the extension .prov. The file contains:

upstream-commit: a1b2c3d4e5f6g7h8i9j0
upstream-repo: https://github.com/example/libfoo
license: MIT
retrieved-at: 2024-09-20T12:34:56Z

• The upstream-commit is the exact SHA‑1 (or SHA‑256) of the upstream commit that introduced the lines now present in the vendored file.
• The upstream-repo points to the public repository, not a private mirror.
• The license field records the licence declared by the upstream project at that commit.
• retrieved-at is a timestamp that can be signed later if required.

Because the file lives in the same directory as the vendored source, it moves with the file during refactors, and it is versioned by Git alongside the code. A simple script can verify the integrity of the provenance record:

#!/usr/bin/env bash
set -e
file=$1
prov="${file}.prov"

commit=$(awk -F': ' '/upstream-commit/ {print $2}' "$prov")
git -C "$(dirname "$file")" cat-file -e "$commit"

If the commit no longer exists in the upstream repository, the script fails, signalling that the provenance is stale and needs re‑validation.

Hook the record into your SBOM pipeline

Most SBOM tools accept an additional JSON file per component. Convert the .prov file to the SPDX PackageVerificationCode format:

{
  "SPDXID": "SPDXRef-Package-foo",
  "name": "libfoo",
  "downloadLocation": "git+https://github.com/example/libfoo@a1b2c3d4e5f6g7h8i9j0",
  "licenseConcluded": "MIT",
  "verificationCode": {
    "value": "a1b2c3d4e5f6g7h8i9j0"
  }
}

When the SBOM is generated, the tool picks up this JSON and records the exact upstream commit. Auditors can then trace any line back to the original source without manual digging. The approach also satisfies the “software provenance” requirement of many compliance frameworks, because the provenance data is stored, versioned, and cryptographically linked to the upstream commit.

Keep the record honest with a build‑intent gate

If your organisation already uses a build‑intent gate to resolve licences, extend the gate to reject any vendored file that lacks a matching .prov file. The gate can also verify that the licence declared in the provenance record matches the licence declared in the upstream repository at that commit. This prevents accidental licence drift when upstream licences change.

Monday’s concrete step

1. Pick a single vendored library that you update regularly.
2. For the most recent upstream commit you have applied, create a <file>.prov file next to the vendored source using the format above.
3. Add a CI job that runs the verification script for every .prov file in the repository.
4. Commit the provenance files and the CI configuration.

By the end of the week you will have a reproducible chain of custody for that library, and the same pattern can be rolled out to the rest of your vendored code. This small discipline eliminates the “paper‑trail debt” described in the pillar post /blog/vendoring-code-without-a-paper-trail-is-unsecured-debt and makes future licence compliance and security patching far less painful.