Record the upstream project and URL, the exact version and commit, the license, the date you imported it, a list of local changes, an owner, and how to update. Eight fields in a small file next to the code answer almost every question an engineer, auditor or buyer will ask later.
Why a file at all
Vendored code has no manifest, so nothing tells you what it is. People leave, directories get renamed, and a year on nobody remembers that the folder is a copy of a library with a known security history. A provenance file is the cheapest fix. It costs ten minutes at import and saves hours at every audit and incident.
The fields
| Field | Example | Why it earns its place |
|---|---|---|
| Name | examplelib | Lets you search advisories |
| Upstream URL | repository address | Where to check for fixes |
| Version | 1.4.2 | Matches advisory ranges |
| Commit | full hash | Exact state, immune to moved tags |
| License | SPDX identifier | Supports notices and policy checks |
| Imported on | 2026-10-19 | Shows how stale it is |
| Local changes | list, with reasons | Shows divergence |
| Owner | team or person | Someone to ask |
| Update method | the command or steps | Makes the next update easy |
| Remove when | condition | Gives an exit |
Use the SPDX identifier for the license, and when the license needs a notice file, note where the notice lives. See what MIT and Apache notices require.
A simple format
Plain text or a small structured file both work. Pick something your tooling can read, so a script can collect all the files into an inventory.
name: examplelib
upstream: https://github.com/example/examplelib
version: 1.4.2
commit: FULL_COMMIT_HASH
license: MIT
imported: 2026-10-19
owner: platform team
local_changes:
- removed network call in init, see commit ABC123
update: re-run scripts/update-examplelib.sh
remove_when: we move to the packaged dependency
Keep it alive
- Make updating the file part of the update script, so it cannot drift.
- Add a continuous integration check that fails if a vendored directory changes and its provenance file does not.
- Collect all provenance files into your SBOM. Many SBOM formats can describe a component with an origin and a list of changes. See describing a fork in a CycloneDX SBOM.
- Review the files at each sync, and delete the ones for code you removed.
What auditors and buyers will do with it
A buyer asking for an SBOM, or a reviewer checking open source obligations, wants to know what third party code you ship. A folder of provenance files is a ready answer and a sign of care. It also shortens incident response: when an advisory lands, you search the files by name and know within minutes whether you ship that code. See vulnerabilities in vendored or copied code.
Where Safeguard fits
Safeguard's SBOM and dependency scanning, plus compliance and evidence automation, can help keep an inventory current. Try a free scan at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen. Look at which fields an inventory shows for each component, then compare them with the table above.
Quick check
Why record the commit and not only the version?
Tags can move and versions can be reused. A full commit hash identifies one exact state of the code.
Who should own the file?
The team that owns the code that uses the vendored library, named in the file so there is someone to ask.
Last reviewed: 19 October 2026.
