Capturing License Metadata at the Build-Intent Gate

Most licensing audits fail because they start after the code has already landed in the tree.

A developer copies a 40-line utility from an upstream library, pastes it into an internal package, and strips the file header during formatting. Or an automated workflow pulls a vendor tarball, unpacks it into third_party/, and commits the result. Weeks later, a static analysis scanner flags a possible GPL infection or an unattributed Apache snippet. By then, the commit message says only "update helpers," the author has forgotten the source URL, and the upstream revision is lost.

Reconstructing the origin of unannotated code after it hits disk is forensic guesswork. As we have argued before, vendoring code without a paper trail is unsecured debt. The fix is not running more scanners in CI. The fix is intercepting the mutation before the disk write happens.

The failure mode of post-hoc scanning

Software composition analysis (SCA) tools inspect files after they are written. They scan source trees for license keywords, regex match against standard headers, or compare ASTs against known public repositories.

This model has three architectural flaws:

1. Context loss: The tool inspects the file in isolation. It cannot see the upstream repository tag, the package manager manifest, or the download URL that introduced it.
2. Ambiguity: Snippets under 50 lines often contain no license header at all. Scanners default to "unknown" or skip them entirely.
3. Reactive enforcement: The bad license is already in the repository history. Removing it requires a rewrite or an awkward compliance PR that leaves the liability in git reflogs.

When you allow arbitrary file writes and attempt to classify them later, you are solving an identity problem after destroying the identity.

Intercepting writes with a Build Intent gate

A Build Intent gate changes the order of operations. No automated tool, synthesizer, or vendoring script writes directly to the workspace. Instead, it submits a proposed write—an intent—to a validation gate.

The intent payload must contain the file path, the proposed content (or its cryptographic hash), and the explicit license metadata and provenance declarations. The gate evaluates these invariants before issuing a terminal state: accept, reject, or require human escalation.

{
  "intent": "vendor_write",
  "target_path": "src/vendor/murmur3/murmur3.go",
  "content_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "provenance": {
    "origin_url": "https://github.com/spaolacci/murmur3",
    "commit": "f0f73a34a2e777d54109787a647e70417bda2723",
    "retrieved_at": "2025-03-01T14:22:10Z"
  },
  "licensing": {
    "spdx_expression": "BSD-3-Clause",
    "attribution_required": true,
    "notice_path": "src/vendor/murmur3/LICENSE"
  }
}

If the proposed write declares an incompatible license (for example, AGPL-3.0 in a proprietary codebase), or if it omits origin information entirely, the gate fails immediately. The write is aborted. The disk is never touched.

If the gate passes, two things happen simultaneously: the file is written, and the gate appends an immutable record to the workspace's provenance registry.

Feeding the SBOM directly

When license metadata and origin hashes are captured at the point of ingestion, generating a Software Bill of Materials (SBOM) stops being a scanning problem. It becomes a simple projection of the intent ledger.

An SBOM generated this way is structural rather than heuristic. Every vendored component, generated file, or copied snippet links to:

• The exact upstream commit or release hash.
• The validated SPDX license identifier.
• The specific write intent that authorized its inclusion in the tree.

This eliminates the "unknown license" noise typical of standard SBOM exports. It also ensures that an SBOM without origin hashes is meaningless ceases to be a description of your repository. If an auditor asks why a particular file is in the tree, you do not point them to a broad git log; you point them to the intent receipt that admitted it.

What is genuinely hard

This model requires discipline at the boundary.

If developers can bypass the gate by dragging files directly into their editor, the chain of custody breaks. The gate must be integrated into your vendoring tooling, your local scaffolding scripts, or your CI pipeline where pull requests are validated.

Second, license metadata is only as good as the upstream source. If an upstream project has an ambiguous root LICENSE file or mixes multi-licensed subdirectories, a human still has to resolve that ambiguity once before constructing the intent payload. The gate does not eliminate legal analysis; it ensures you only have to do it once, and that your conclusions are enforced automatically from that moment on.

What to do on Monday

Do not buy a new compliance suite. Start with the scripts that vendor your dependencies:

1. Wrap your vendoring steps. If you use go mod vendor, cargo vendor, or custom curl scripts, wrap them in a task that writes an intent.json alongside the fetched artifacts.
2. Require provenance fields. Make three fields mandatory in that manifest: origin URL, exact commit SHA, and SPDX license ID.
3. Block untracked additions in CI. Add a pre-commit or CI check that fails if any file under your vendor directory lacks a corresponding entry in the intent manifest.

When you enforce provenance at the gate, license compliance stops being a periodic panic and becomes a standard property of the build.