Enforcing Provenance for Vendored Code with SHPBL

Forked repos become a “folder of hope”

A team clones an upstream library, removes the .git directory, and copies the files into a private monorepo. The original licence headers disappear, the commit graph is lost, and every line now sits behind an undocumented wall. During a security audit the team is asked, “Who wrote this function?” The answer is “We don’t know”. That uncertainty is a liability. In a supply‑chain breach the missing provenance makes it impossible to prove that the vendored code complies with the organisation’s license‑compliance policy.

Why the build pipeline must enforce software provenance

Provenance is only useful when it can be verified automatically. A static checklist that “someone checked the licences” does not survive a code‑review churn or a CI rebuild on a new branch. The failure mode is a missing or stale provenance record that the build system never validates. The correct posture is to make the build step the single source of truth for:

• the upstream commit hash or tag that the vendored snapshot derives from,
• the licence file(s) that accompany that snapshot,
• a hash of the exact tarball that was used.

When the pipeline records these invariants, any later change that alters the vendored code without updating the provenance record is rejected. The result is a reproducible, auditable trail that survives forks, rebases, and private mirrors.

Worked example: a CI gate for vendored tarballs

Consider a private repository that vendors lodash version 4.17.21. The team stores the tarball in vendor/lodash.tgz. A minimal CI job can enforce provenance as follows:

## .github/workflows/provenance.yml
name: Vendored provenance
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Verify upstream hash
        run: |
          EXPECTED_HASH=9c9e9b8f5e3a4b1c2d6e7f8a9b0c1d2e3f4a5b6c
          ACTUAL_HASH=$(sha256sum vendor/lodash.tgz | cut -d' ' -f1)
          if [ "$ACTUAL_HASH" != "$EXPECTED_HASH" ]; then
            echo "::error::Lodash tarball hash mismatch"
            exit 1
          fi
      - name: Verify licence header
        run: |
          grep -q "MIT License" vendor/lodash/LICENSE || {
            echo "::error::Licence header missing"
            exit 1
          }

The job stores the expected hash in source control. Any change to the tarball—whether intentional or accidental—fails the gate, forcing the developer to update the provenance record together with the vendored code. The same pattern can be applied to whole directories: compute a Merkle tree of file hashes, store the root hash, and compare it on each CI run.

How SHPBL makes provenance enforcement repeatable

SHPBL provides a model‑independent library that extracts upstream invariants from any repository and stores them in a certified artifact. The library can be called through the MCP server, the plain HTTP API, the typed TypeScript client (@shpbl/sdk), or the offline file‑based edition—​all the same gate, the same meter. A certification harness then executes the artifact and returns a verdict: CERTIFIED when the provenance checks pass, PROVISIONAL when the artifact is reproducible but not yet fully validated, INCONCLUSIVE when the harness cannot exercise the contract, or FAILED when invariants are broken.

Using the free repository evaluation lane (/evaluation) you can upload a vendored tarball and see the exact licence and commit hash SHPBL extracts. The same process can be baked into your CI pipeline via the HTTP API (/api-access) or the TypeScript client (/sdk). Because the library is repeatable and its release archives are sealed by published checksums (/root-of-trust), you get a paper‑trail that survives forks and private mirrors without relying on any AI‑generated inference.

Monday’s concrete step

1. Identify one vendored component that currently lives without licence headers.
2. Run a free evaluation at /evaluation and note the extracted upstream hash and licence file.
3. Add a CI job similar to the example above that checks the stored hash and licence before the build proceeds.
4. Commit the CI definition and the provenance record together.

By the end of the day you will have turned a “folder of hope” into a verifiable, auditable piece of your supply chain. For a deeper dive see the pillar post Vendoring code without a paper trail is unsecured debt and the related case studies at /case-studies.